From cde9f8272a8ae1a7221c8e8b738462b95dc57b70 Mon Sep 17 00:00:00 2001
From: aron <263346377+aron-cf@users.noreply.github.com>
Date: Thu, 15 Oct 2026 12:35:15 +0100
Subject: [PATCH 1/5] chore: Make Workspace and WorkerJavaScriptBackend stable

---
 .changeset/stable-status.md                   |  5 ++
 .github/SECURITY.md                           |  3 +-
 README.md                                     | 22 +++++--
 docs/02_sync_protocol.md                      |  5 ++
 docs/07_injected_service.md                   |  5 ++
 docs/08_capnweb_interface.md                  |  5 ++
 docs/12_worker_backend.md                     |  5 ++
 docs/17_isolate_javascript.md                 |  7 ++-
 docs/README.md                                | 59 ++++++++++--------
 examples/assets/README.md                     |  4 --
 examples/container-legacy/README.md           |  9 ++-
 examples/container/README.md                  |  9 ++-
 examples/egress/README.md                     |  6 +-
 examples/think/README.md                      |  9 ++-
 examples/tutorial/README.md                   |  9 ++-
 examples/vite-bundle/README.md                |  6 +-
 examples/worker-javascript/README.md          |  4 --
 examples/worker-javascript/wrangler.jsonc     |  2 +-
 examples/worker-shell/README.md               |  6 +-
 .../computer-computerd-linux-x64/README.md    | 10 +--
 packages/computer/README.md                   | 62 +++++++++++++++----
 .../container-legacy/cloudflare-container.ts  |  6 ++
 .../container-legacy/container-host.ts        |  6 ++
 .../src/backends/container-legacy/index.ts    |  3 +
 .../backends/container/container-backend.ts   |  6 ++
 .../src/backends/container/container-host.ts  |  6 ++
 .../computer/src/backends/container/index.ts  |  3 +
 .../src/backends/worker-javascript/index.ts   |  7 +++
 .../src/backends/worker-shell/index.ts        |  5 +-
 .../src/backends/worker-shell/worker-shell.ts |  6 ++
 packages/computer/src/index.ts                |  4 ++
 packages/computerd/README.md                  | 10 +--
 packages/dofs/README.md                       | 17 ++---
 packages/dofs/src/index.ts                    |  5 ++
 packages/rpc/README.md                        | 10 +--
 packages/rpc/src/index.ts                     |  2 +
 36 files changed, 243 insertions(+), 105 deletions(-)
 create mode 100644 .changeset/stable-status.md

diff --git a/.changeset/stable-status.md b/.changeset/stable-status.md
new file mode 100644
index 00000000..51da6c8d
--- /dev/null
+++ b/.changeset/stable-status.md
@@ -0,0 +1,5 @@
+---
+"@cloudflare/computer": patch
+---
+
+Mark the `Workspace`, its filesystem, the worker-javascript backend, mounts, agent tools, Git, Assets, and Artifacts as stable; the container and worker-shell backends, `ws:container`, sync, and `computerd` stay experimental.
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
index b102a551..9585bfb7 100644
--- a/.github/SECURITY.md
+++ b/.github/SECURITY.md
@@ -1,7 +1,6 @@
 # Security Policy
 
 > [!IMPORTANT]
-> Cloudflare Computer is in an early preview/experimental state and is under active, rapid development.
-> Please treat any deployment as experimental and do not rely on it for production security guarantees.
+> Parts of Cloudflare Computer are stable and parts are experimental. Most of it is stable. The container backends, the Worker shell backend, the `ws:container` host module, the sync between the durable object and `computerd`, `computerd` itself, and the RPC package are experimental and under active development; the [status table](../packages/computer/README.md#status) has the full list. Do not rely on the experimental components for production security guarantees.
 > 
 > Reporting a security issue: If you find what you believe to be a security issue, please open a GitHub issue in this repository describing it. 
diff --git a/README.md b/README.md
index 99eb0c50..fabe8985 100644
--- a/README.md
+++ b/README.md
@@ -26,11 +26,17 @@ Workspace can also be constructed without a backend at all, giving
 callers the filesystem on its own.
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
+> Most of Cloudflare Computer is stable, meaning suitable for
+> production use: the `Workspace`, its SQLite filesystem
+> (`@cloudflare/dofs`), the Isolate JavaScript backend, mounts, agent
+> tools, Git, Assets, and Artifacts.
 >
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> The experimental parts are the container backends, the Worker shell backend, the `ws:container`
+> host module, the sync between the durable object and `computerd`,
+> `computerd` itself, and the RPC package. Their APIs
+> may change in any release, and they are not yet suitable for production
+> use. The [`@cloudflare/computer` status table](packages/computer/README.md#status)
+> has the full list.
 >
 > The specification under [`docs/`](docs/) is forward-looking — read it for
 > intent, not as description of the code today.
@@ -111,18 +117,24 @@ package-specific status and usage notes.
 - [`packages/dofs`](packages/dofs/README.md) (`@cloudflare/dofs`) —
   Durable Object SQLite-backed virtual filesystem, sync protocol
   building blocks, and a `@platformatic/vfs` provider for Node.
+  Stable, except the sync protocol building blocks.
 - [`packages/rpc`](packages/rpc/README.md)
   (`@cloudflare/computer-rpc`) — capnweb wire types and
   server/client helpers shared between the Durable Object and `computerd`.
+  Experimental.
 - [`packages/computerd`](packages/computerd/README.md)
   (`@cloudflare/computerd`) — the `computerd` daemon: a FUSE mount plus
   HTTP/WebSocket RPC server that runs inside the sandbox container.
+  Experimental.
 - [`packages/computer`](packages/computer/README.md)
   (`@cloudflare/computer`) — the top-level Computer package
-  consumed by Durable Objects. Work in progress.
+  consumed by Durable Objects. Stable, except the container and Worker
+  shell backends and the pieces listed as experimental in its
+  [status table](packages/computer/README.md#status).
 - [`packages/computer-computerd-linux-x64`](packages/computer-computerd-linux-x64/README.md)
   — private Docker image context for the prebuilt `computerd` linux-x64
   binary. The image, not an npm package, is the release artifact.
+  Experimental.
 
 ## Performance
 
diff --git a/docs/02_sync_protocol.md b/docs/02_sync_protocol.md
index 08b68c0b..e6d3389d 100644
--- a/docs/02_sync_protocol.md
+++ b/docs/02_sync_protocol.md
@@ -1,5 +1,10 @@
 # 02. Sync Protocol
 
+> [!WARNING]
+> **Experimental.** The sync protocol between the durable object and `computerd` may change in any release and
+> is not yet suitable for production use. See the
+> [status table](../packages/computer/README.md#status).
+
 > [!NOTE]
 > This document tracks the shipped wire shape in `packages/dofs/src/sync/*`
 > and `packages/rpc/src/{interface,server,sync-driver}.ts`. A handful of
diff --git a/docs/07_injected_service.md b/docs/07_injected_service.md
index a863262e..9e715fef 100644
--- a/docs/07_injected_service.md
+++ b/docs/07_injected_service.md
@@ -1,5 +1,10 @@
 # 07. Injected Service
 
+> [!WARNING]
+> **Experimental.** `computerd` and the container backends may change in any release and
+> is not yet suitable for production use. See the
+> [status table](../packages/computer/README.md#status).
+
 > [!NOTE]
 > This doc now reflects shipped code in `packages/computerd/` and
 > `packages/computer/src/backends/`. Items marked **(planned)** are
diff --git a/docs/08_capnweb_interface.md b/docs/08_capnweb_interface.md
index 956ebd8a..56429816 100644
--- a/docs/08_capnweb_interface.md
+++ b/docs/08_capnweb_interface.md
@@ -1,5 +1,10 @@
 # 08. Capnweb Interface
 
+> [!WARNING]
+> **Experimental.** The capnweb wire protocol and `@cloudflare/computer-rpc` may change in any release and
+> is not yet suitable for production use. See the
+> [status table](../packages/computer/README.md#status).
+
 > [!NOTE]
 > This doc now reflects shipped code in `packages/rpc/`. Items marked
 > **(planned)** are deferred work.
diff --git a/docs/12_worker_backend.md b/docs/12_worker_backend.md
index 1bba49b5..a2026e38 100644
--- a/docs/12_worker_backend.md
+++ b/docs/12_worker_backend.md
@@ -1,5 +1,10 @@
 # 12. Worker backend
 
+> [!WARNING]
+> **Experimental.** The Worker shell backend (`WorkerShellBackend`) may change in any release and
+> is not yet suitable for production use. See the
+> [status table](../packages/computer/README.md#status).
+
 > [!NOTE]
 > This doc reflects shipped code in
 > `packages/computer/src/backends/worker-shell/`. The example deployment
diff --git a/docs/17_isolate_javascript.md b/docs/17_isolate_javascript.md
index a6d6ae01..1225ade2 100644
--- a/docs/17_isolate_javascript.md
+++ b/docs/17_isolate_javascript.md
@@ -1,5 +1,10 @@
 # Isolate JavaScript runtime
 
+> [!NOTE]
+> **Stable.** `WorkerJavaScriptBackend` and its host modules are
+> suitable for production use, except `ws:container`, which runs on the
+> experimental container backend. See the [status table](../packages/computer/README.md#status).
+
 `WorkerJavaScriptBackend` runs an ECMAScript module in a fresh Cloudflare Dynamic Worker:
 
 ```ts
@@ -178,7 +183,7 @@ An import that is not built in, configured, one of the allowed Node.js modules,
 
 The allowed Node.js modules are the ones that work entirely inside the isolate: `node:path`, `node:url`, `node:util`, `node:events`, `node:buffer`, `node:assert`, `node:string_decoder`, `node:querystring`, `node:stream`, `node:crypto`, `node:zlib`, `node:timers`, `node:async_hooks`, and `node:diagnostics_channel`, with their subpaths such as `node:path/posix` and `node:timers/promises`. The runtime provides them, and imports of them are left as written. A bare name such as `path` works too and becomes `node:path`, unless a configured module has that name, in which case the configured module wins. The runtime has more Node.js modules, but they either duplicate what the Workspace provides, as `node:fs` does, reach outside the isolate, or are stubs that throw when called, so they stay unavailable.
 
-Any import that is not a path is resolved by name. The Worker Loader has no `node_modules` lookup and resolves a bare import next to the importing file, so Workspace stores each source and host module once, in a `__modules__` directory of the Worker's bundle, and rewrites every import of one into a relative path to it. Every file that imports `lodash` gets the same instance, however many directories the code spans. An absolute import is rewritten the same way. Relative paths are the only form the Worker Loader's legacy and new module registries resolve alike, so imports work whether or not `compatibilityFlags` includes `new_module_registry`. When a module fails to link, the error names it as the code wrote it.
+Any import that is not a path is resolved by name. The Worker Loader has no `node_modules` lookup and resolves a bare import next to the importing file, so Workspace stores each source and host module once, in a `__modules__` directory of the Worker's bundle, and rewrites every import of one into a relative path to it. Every file that imports `lodash` gets the same instance, however many directories the code spans. An absolute import is rewritten the same way. Relative paths are the only form the Worker Loader's legacy and new module registries resolve alike, so imports work whether or not `compatibilityFlags` includes `new_module_registry`. The Workers runtime still treats `new_module_registry` as experimental, so a Worker that adds it also needs the `experimental` compatibility flag; the default settings need neither. When a module fails to link, the error names it as the code wrote it.
 
 The backend describes its modules for a model in `backend.description`, which `workspace.runtime.backends()` returns and the `exec` tool shows. It is built from the same `modules` option the backend runs with, so it always matches what is installed:
 
diff --git a/docs/README.md b/docs/README.md
index ce841b39..04f1d938 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,11 +1,14 @@
 # `@cloudflare/computer`
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> Most of Cloudflare Computer is stable, meaning suitable for
+> production use. The experimental parts are the container backends, the Worker shell backend, the `ws:container`
+> host module, the sync between the durable object and `computerd`,
+> `computerd` itself, and the RPC package. Their APIs
+> may change in any release, and they are not yet suitable for production
+> use. The topic index below marks each document's status, and the
+> [`@cloudflare/computer` status table](../packages/computer/README.md#status)
+> has the full list.
 >
 > The specification in this directory is forward-looking — read it for
 > intent, not as description of the code today.
@@ -238,27 +241,31 @@ events.addEventListener("exit",   (e) => { console.log("exit", JSON.parse(e.data
 This package is documented as a set of focused topics. Start with the overview
 above, then dive into the area you're working on.
 
-| Document | Topic |
-| --- | --- |
-| [01. VFS](./01_vfs.md) | Layout of the workspace tree, reserved paths, and mount points. |
-| [02. Sync Protocol](./02_sync_protocol.md) | How the DO-backed VFS synchronises with the sandbox container. |
-| [03. Filesystem Schema](./03_filesystem_schema.md) | SQLite schema backing the virtual filesystem. |
-| [04. Filesystem Interface](./04_filesystem_interface.md) | `Workspace.fs` API: `readFile`, `writeFile`, `mkdir`, `grep`, etc. |
-| [05. Runtime Interface](./05_runtime_interface.md) | `Workspace.runtime.exec/getExec/killExec/disposeExec` and backend routing. |
-| [06. Mount Interface](./06_mount_interface.md) | Pre-filling paths from R2, Artifacts, GitHub, and custom sources. **(not yet implemented)** |
-| [07. Injected Service](./07_injected_service.md) | The in-container `computerd` service that backs FUSE and shell. |
-| [08. Capnweb Interface](./08_capnweb_interface.md) | RPC wire protocol between the DO and the sandbox. |
-| [09. Tool Interface (Agents)](./09_tool_interface.md) | Ready-made AI SDK tools for `@cloudflare/agents`. |
-| [10. Project Layout](./10_project_layout.md) | Source tree of this package and how the pieces fit together. |
-| [11. Lifecycle](./11_lifecycle.md) | DO incarnations, container lifetime, capnweb session lifecycle, and hibernation. |
-| [12. Worker backend](./12_worker_backend.md) | Running the shell as just-bash inside a Dynamic Worker loaded through `env.LOADER`. |
-| [13. Git interface](./13_git_interface.md) | `workspace.git` and the `git` CLI inside the shell, backed by isomorphic-git. |
-| [14. Assets interface](./14_assets_interface.md) | `share` a workspace file to R2 and get back a presigned URL. |
-| [15. Artifacts interface](./15_artifacts_interface.md) | `createArtifact` and the `artifacts` CLI, an optionally session-scoped wrapper over the Cloudflare Artifacts binding. |
-| [16. Execution runtime architecture](./16_code_execution.md) | One runtime entry point over command and module backends. |
-| [17. Isolate JavaScript runtime](./17_isolate_javascript.md) | ECMAScript modules, durable imports, configured libraries, durable `node:fs/promises`, host modules, and managed lifecycle. |
-| [18. Runtime migration](./18_runtime_migration.md) | Breaking preview-API mappings from public shell and script-execution surfaces to `workspace.runtime`. |
-| [19. Performance](./19_performance.md) | Filesystem benchmarks: `fs-bench` numbers, an `npm install` comparison, and how to reproduce them. |
+The status column says whether the API a document describes is stable or
+experimental. Reference documents describe the code or its performance
+rather than an API.
+
+| Document | Status | Topic |
+| --- | --- | --- |
+| [01. VFS](./01_vfs.md) | Stable | Layout of the workspace tree, reserved paths, and mount points. |
+| [02. Sync Protocol](./02_sync_protocol.md) | Experimental | How the DO-backed VFS synchronises with the sandbox container. |
+| [03. Filesystem Schema](./03_filesystem_schema.md) | Stable | SQLite schema backing the virtual filesystem. |
+| [04. Filesystem Interface](./04_filesystem_interface.md) | Stable | `Workspace.fs` API: `readFile`, `writeFile`, `mkdir`, `grep`, etc. |
+| [05. Runtime Interface](./05_runtime_interface.md) | Stable | `Workspace.runtime.exec/getExec/killExec/disposeExec` and backend routing. |
+| [06. Mount Interface](./06_mount_interface.md) | Stable | Pre-filling paths from R2, Artifacts, GitHub, and custom sources. **(not yet implemented)** |
+| [07. Injected Service](./07_injected_service.md) | Experimental | The in-container `computerd` service that backs FUSE and shell. |
+| [08. Capnweb Interface](./08_capnweb_interface.md) | Experimental | RPC wire protocol between the DO and the sandbox. |
+| [09. Tool Interface (Agents)](./09_tool_interface.md) | Stable | Ready-made AI SDK tools for `@cloudflare/agents`. |
+| [10. Project Layout](./10_project_layout.md) | Reference | Source tree of this package and how the pieces fit together. |
+| [11. Lifecycle](./11_lifecycle.md) | Mixed: stub disposal is stable; the container and capnweb lifecycle are experimental | DO incarnations, container lifetime, capnweb session lifecycle, and hibernation. |
+| [12. Worker backend](./12_worker_backend.md) | Experimental | Running the shell as just-bash inside a Dynamic Worker loaded through `env.LOADER`. |
+| [13. Git interface](./13_git_interface.md) | Stable | `workspace.git` and the `git` CLI inside the shell, backed by isomorphic-git. |
+| [14. Assets interface](./14_assets_interface.md) | Stable | `share` a workspace file to R2 and get back a presigned URL. |
+| [15. Artifacts interface](./15_artifacts_interface.md) | Stable | `createArtifact` and the `artifacts` CLI, an optionally session-scoped wrapper over the Cloudflare Artifacts binding. |
+| [16. Execution runtime architecture](./16_code_execution.md) | Stable | One runtime entry point over command and module backends. |
+| [17. Isolate JavaScript runtime](./17_isolate_javascript.md) | Stable, except `ws:container` | ECMAScript modules, durable imports, configured libraries, durable `node:fs/promises`, host modules, and managed lifecycle. |
+| [18. Runtime migration](./18_runtime_migration.md) | Reference | Breaking preview-API mappings from public shell and script-execution surfaces to `workspace.runtime`. |
+| [19. Performance](./19_performance.md) | Reference | Filesystem benchmarks: `fs-bench` numbers, an `npm install` comparison, and how to reproduce them. |
 
 ## High-level API
 
diff --git a/examples/assets/README.md b/examples/assets/README.md
index a08dcf59..f5952c4f 100644
--- a/examples/assets/README.md
+++ b/examples/assets/README.md
@@ -1,9 +1,5 @@
 # assets example
 
-> [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
-
 A Cloudflare Worker + Durable Object that turns a text prompt into
 an image and hands back a shareable link. One shot: `POST /prompt`,
 get a URL.
diff --git a/examples/container-legacy/README.md b/examples/container-legacy/README.md
index 5d117277..36736794 100644
--- a/examples/container-legacy/README.md
+++ b/examples/container-legacy/README.md
@@ -1,11 +1,10 @@
 # container example
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> This example uses experimental parts of Cloudflare Computer: the legacy container backend and `computerd`.
+> Their APIs may change in any release, and they are not yet suitable
+> for production use. See the
+> [status table](../../packages/computer/README.md#status).
 
 A Cloudflare Worker + Durable Object that boots a Container running
 the `computerd` daemon and exposes a minimal `write` / `read` / `exec`
diff --git a/examples/container/README.md b/examples/container/README.md
index 32d05809..46ae6e05 100644
--- a/examples/container/README.md
+++ b/examples/container/README.md
@@ -1,11 +1,10 @@
 # container example
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> This example uses experimental parts of Cloudflare Computer: the container backend and `computerd`.
+> Their APIs may change in any release, and they are not yet suitable
+> for production use. See the
+> [status table](../../packages/computer/README.md#status).
 
 A Cloudflare Worker + Durable Object that boots a Container running the
 `computerd` daemon and exposes a minimal `write` / `read` / `exec` HTTP
diff --git a/examples/egress/README.md b/examples/egress/README.md
index 72279677..a55633aa 100644
--- a/examples/egress/README.md
+++ b/examples/egress/README.md
@@ -1,8 +1,10 @@
 # egress example
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
+> This example uses experimental parts of Cloudflare Computer: the container and Worker shell backends and `computerd`.
+> Their APIs may change in any release, and they are not yet suitable
+> for production use. See the
+> [status table](../../packages/computer/README.md#status).
 
 This Worker sends one URL through all three Cloudflare Computer execution backends:
 
diff --git a/examples/think/README.md b/examples/think/README.md
index f6cd582d..8229a7f8 100644
--- a/examples/think/README.md
+++ b/examples/think/README.md
@@ -1,11 +1,10 @@
 # `@cloudflare/think` chat example
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> This example uses experimental parts of Cloudflare Computer: the container and Worker shell backends and `computerd`.
+> Their APIs may change in any release, and they are not yet suitable
+> for production use. See the
+> [status table](../../packages/computer/README.md#status).
 
 A minimal example that puts [`@cloudflare/think`][think] behind a
 terminal chat interface. The agent is a Durable Object with a
diff --git a/examples/tutorial/README.md b/examples/tutorial/README.md
index 64f7741f..8c6aea84 100644
--- a/examples/tutorial/README.md
+++ b/examples/tutorial/README.md
@@ -1,11 +1,10 @@
 # Tutorial: a PDF recipe card agent
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> This example uses experimental parts of Cloudflare Computer: the legacy container backend and `computerd`.
+> Their APIs may change in any release, and they are not yet suitable
+> for production use. See the
+> [status table](../../packages/computer/README.md#status).
 
 A worker with one endpoint. You post a dish, an agent finds a matching
 recipe on [openstove.org](https://openstove.org/recipes), writes a
diff --git a/examples/vite-bundle/README.md b/examples/vite-bundle/README.md
index 10426b08..19e5cd09 100644
--- a/examples/vite-bundle/README.md
+++ b/examples/vite-bundle/README.md
@@ -1,8 +1,10 @@
 # vite-bundle example
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
+> This example uses experimental parts of Cloudflare Computer: the Worker shell backend.
+> Their APIs may change in any release, and they are not yet suitable
+> for production use. See the
+> [status table](../../packages/computer/README.md#status).
 
 A Vite-built Cloudflare Worker + Durable Object whose Workspace ships a
 directory from the project, `src/skills`, into every workspace. It uses
diff --git a/examples/worker-javascript/README.md b/examples/worker-javascript/README.md
index d4de408d..4334d2a1 100644
--- a/examples/worker-javascript/README.md
+++ b/examples/worker-javascript/README.md
@@ -1,9 +1,5 @@
 # worker-javascript example
 
-> [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
-
 A Cloudflare Worker + Durable Object that runs a Workspace whose
 runtime evaluates **ECMAScript modules** in a **Dynamic Worker**
 loaded through `env.LOADER`. It mirrors
diff --git a/examples/worker-javascript/wrangler.jsonc b/examples/worker-javascript/wrangler.jsonc
index fad31603..8d8000bc 100644
--- a/examples/worker-javascript/wrangler.jsonc
+++ b/examples/worker-javascript/wrangler.jsonc
@@ -11,7 +11,7 @@
   "name": "computer-worker-javascript-example",
   "main": "src/index.ts",
   "compatibility_date": "2026-05-26",
-  "compatibility_flags": ["nodejs_compat", "experimental"],
+  "compatibility_flags": ["nodejs_compat"],
 
   // Upload every file under src/skills as its own module, under its
   // path relative to src/, so it shows up at /bundle/skills/... and
diff --git a/examples/worker-shell/README.md b/examples/worker-shell/README.md
index 74382dd1..d46787fc 100644
--- a/examples/worker-shell/README.md
+++ b/examples/worker-shell/README.md
@@ -1,8 +1,10 @@
 # worker-shell example
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
+> This example uses experimental parts of Cloudflare Computer: the Worker shell backend.
+> Their APIs may change in any release, and they are not yet suitable
+> for production use. See the
+> [status table](../../packages/computer/README.md#status).
 
 A Cloudflare Worker + Durable Object that runs a Workspace whose
 shell is a **Dynamic Worker** loaded through `env.LOADER`. The
diff --git a/packages/computer-computerd-linux-x64/README.md b/packages/computer-computerd-linux-x64/README.md
index 238af114..aaf7404f 100644
--- a/packages/computer-computerd-linux-x64/README.md
+++ b/packages/computer-computerd-linux-x64/README.md
@@ -1,11 +1,11 @@
 # @cloudflare/computer-computerd-linux-x64
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This image is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration, and prototypes. It is not suitable
-> for production use at this time.
+> **Experimental.** This image is provided for feedback only. Its APIs
+> may change in any release, and it is not suitable for production use
+> yet. Suitable for experiments, exploration, and prototypes. See the
+> [`@cloudflare/computer` status table](../computer/README.md#status)
+> for which components are stable.
 
 Docker image context for the prebuilt `computerd` linux-x64 binary.
 `computerd` is the daemon side of [`@cloudflare/computer`](../computer) —
diff --git a/packages/computer/README.md b/packages/computer/README.md
index 81799049..e90144cd 100644
--- a/packages/computer/README.md
+++ b/packages/computer/README.md
@@ -6,10 +6,43 @@ small, portable working directory and the tools to read, write, and run
 things in it.
 
 > [!IMPORTANT]
-> **PREVIEW ONLY.** This package is provided as a preview for feedback
-> only. APIs are unstable and the design is subject to change. Suitable
-> for experiments, exploration, and prototypes. It is NOT suitable for
-> production use at this time.
+> Most of this package is stable. The container backends, the Worker
+> shell backend, the `ws:container` host module, the sync between the
+> durable object and `computerd`, and `computerd` itself are
+> experimental. See [Status](#status) for the full list.
+
+## Status
+
+Stable means suitable for production use. Experimental APIs are
+provided for feedback: they may change or go away in any release, so
+use them for experiments and prototypes only.
+
+| Component | Entrypoint | Status |
+| --- | --- | --- |
+| `Workspace`, `withWorkspace`, `getWorkspace`, `workspace.fs`, `workspace.runtime`, and the stub types | `@cloudflare/computer` | Stable |
+| The SQLite filesystem layer (`@cloudflare/dofs`, bundled into this package), including `SQLiteWorkspaceProvider` | `@cloudflare/computer` | Stable |
+| `WorkerJavaScriptBackend` | `@cloudflare/computer/backends/worker-javascript` | Stable |
+| Read-only mounts (`R2Bucket`, `WorkerBundle`) and the Vite plugin | `@cloudflare/computer`, `@cloudflare/computer/vite` | Stable |
+| Agent tools | `@cloudflare/computer/tools`, `@cloudflare/computer/tools/*` | Stable |
+| Host modules for isolate JavaScript: `ws:git`, `ws:artifacts`, `ws:assets`, `ws:tools` | `@cloudflare/computer/modules/git`, `modules/artifacts`, `modules/assets`, `modules/tools` | Stable |
+| Git | `@cloudflare/computer/git` | Stable |
+| Assets and Artifacts | `@cloudflare/computer/assets`, `@cloudflare/computer/artifacts` | Stable |
+| Observability hook and its Cloudflare adapter | `@cloudflare/computer`, `@cloudflare/computer/observe/cloudflare` | Stable |
+| `ContainerBackend` and `withWorkspaceContainer` | `@cloudflare/computer/backends/container` | Experimental |
+| `LegacyContainerBackend` and `withLegacyWorkspaceContainer` | `@cloudflare/computer/backends/container-legacy` | Experimental |
+| `WorkerShellBackend` and the shell command groups | `@cloudflare/computer/backends/worker-shell`, `@cloudflare/computer/shell/*` | Experimental |
+| The `ws:container` host module | `@cloudflare/computer/modules/container` | Experimental |
+| `workspace.push()`, `workspace.pull()`, and the sync protocol between the durable object and `computerd` | `@cloudflare/computer` | Experimental |
+| The `computerd` daemon and its container image | `ghcr.io/cloudflare/computer-computerd-linux-x64` | Experimental |
+| The RPC wire protocol between the durable object and `computerd` (`@cloudflare/computer-rpc`) | Internal | Experimental |
+
+A stable surface that runs work on a backend, such as the agent tools'
+`exec` tool, is only as stable as the backend it runs on.
+
+The sync building blocks inside `@cloudflare/dofs` (`applyChanges`,
+`fetchChanges`, watermarks, and the rest) serve only the sync protocol,
+so they share its experimental status. The rest of `@cloudflare/dofs`
+is stable.
 
 ## What you get
 
@@ -45,8 +78,8 @@ npm install @cloudflare/computer
 ```
 
 Your Worker needs the `nodejs_compat` compatibility flag. The
-worker-shell and worker-javascript backends additionally need the
-`experimental` flag and a Worker Loader binding. Each backend has its
+worker-shell and worker-javascript backends also need a Worker Loader
+binding, and the worker-shell backend needs the `experimental` flag. Each backend has its
 own binding requirements — see [Choosing a backend](#choosing-a-backend).
 
 Optional peer dependencies, installed only if you use the matching
@@ -99,7 +132,9 @@ export default {
 
 To run commands against those files, add an execution backend. The
 worker-shell backend needs no container and no Docker, so it's the
-quickest way to get `exec` working:
+quickest way to get `exec` working. It is experimental; for a stable
+backend, use the worker-javascript backend, shown in
+[`examples/worker-javascript`](../../examples/worker-javascript):
 
 ```ts
 import { withWorkspace, getWorkspace } from "@cloudflare/computer";
@@ -274,12 +309,12 @@ Alongside `exec`, the runtime exposes `getExec`, `killExec`, and
 
 ### Choosing a backend
 
-| Backend | Import | Runs | Needs |
-| --- | --- | --- | --- |
-| **Container** | `@cloudflare/computer/backends/container` | Shell commands in full Linux userland (real binaries, `npm`, `node`, network) | A Cloudflare Container running `computerd`, scheduled by the durable object (`scheduling_policy: "durable_object"`) |
-| **Container (legacy)** | `@cloudflare/computer/backends/container-legacy` | The same | A Cloudflare Container the platform schedules and sizes from the `containers` block |
-| **Worker shell** | `@cloudflare/computer/backends/worker-shell` | Shell commands via [just-bash](https://github.com/vercel-labs/just-bash) in a Dynamic Worker | A Worker Loader binding; `experimental` flag |
-| **Worker JavaScript** | `@cloudflare/computer/backends/worker-javascript` | ECMAScript modules in a fresh Dynamic Worker | A Worker Loader binding; `experimental` flag |
+| Backend | Status | Import | Runs | Needs |
+| --- | --- | --- | --- | --- |
+| **Container** | Experimental | `@cloudflare/computer/backends/container` | Shell commands in full Linux userland (real binaries, `npm`, `node`, network) | A Cloudflare Container running `computerd`, scheduled by the durable object (`scheduling_policy: "durable_object"`) |
+| **Container (legacy)** | Experimental | `@cloudflare/computer/backends/container-legacy` | The same | A Cloudflare Container the platform schedules and sizes from the `containers` block |
+| **Worker shell** | Experimental | `@cloudflare/computer/backends/worker-shell` | Shell commands via [just-bash](https://github.com/vercel-labs/just-bash) in a Dynamic Worker | A Worker Loader binding; `experimental` flag |
+| **Worker JavaScript** | Stable | `@cloudflare/computer/backends/worker-javascript` | ECMAScript modules in a fresh Dynamic Worker | A Worker Loader binding |
 
 - **Container** cold-starts more slowly but gives you a real Linux
   environment. The container owns its own SQLite-backed VFS and this
@@ -580,6 +615,7 @@ An adapter for the Cloudflare runtime lives at
 ## Documentation
 
 The design specification lives under [`docs/`](../../docs/README.md).
+Its topic index marks each document stable or experimental.
 Start with [01. VFS](../../docs/01_vfs.md),
 [04. Filesystem Interface](../../docs/04_filesystem_interface.md), and
 [05. Runtime Interface](../../docs/05_runtime_interface.md). It is
diff --git a/packages/computer/src/backends/container-legacy/cloudflare-container.ts b/packages/computer/src/backends/container-legacy/cloudflare-container.ts
index b9b9249d..d22af393 100644
--- a/packages/computer/src/backends/container-legacy/cloudflare-container.ts
+++ b/packages/computer/src/backends/container-legacy/cloudflare-container.ts
@@ -178,6 +178,12 @@ function bearerMatches(header: string | null, expected: string | undefined): boo
   return differences === 0;
 }
 
+/**
+ * Runs shell commands in a platform-scheduled Cloudflare Container through `computerd`.
+ *
+ * Experimental: this API may change in any release and is not yet
+ * suitable for production use.
+ */
 export class LegacyContainerBackend implements WorkspaceBackend {
   readonly type = "cloudflare-container";
   readonly id: string;
diff --git a/packages/computer/src/backends/container-legacy/container-host.ts b/packages/computer/src/backends/container-legacy/container-host.ts
index 4e94567a..9d46147f 100644
--- a/packages/computer/src/backends/container-legacy/container-host.ts
+++ b/packages/computer/src/backends/container-legacy/container-host.ts
@@ -345,6 +345,12 @@ export type WithWorkspaceContainerCtor<TBase extends DOCtor> = TBase &
     ...args: any[]
   ) => InstanceType<TBase> & { getWorkspaceContainer(): LegacyWorkspaceContainerAPI });
 
+/**
+ * Adds the container host surface that `LegacyContainerBackend` dials to a durable object class.
+ *
+ * Experimental: this API may change in any release and is not yet
+ * suitable for production use.
+ */
 export function withLegacyWorkspaceContainer<TBase extends DOCtor>(
   Base: TBase,
 ): WithWorkspaceContainerCtor<TBase> {
diff --git a/packages/computer/src/backends/container-legacy/index.ts b/packages/computer/src/backends/container-legacy/index.ts
index 3dc93649..88adf749 100644
--- a/packages/computer/src/backends/container-legacy/index.ts
+++ b/packages/computer/src/backends/container-legacy/index.ts
@@ -26,6 +26,9 @@
 //     LegacyContainerBackend,
 //     withLegacyWorkspaceContainer,
 //   } from "@cloudflare/computer/backends/container-legacy";
+//
+// Status: experimental. This entry point may change in any release
+// and is not yet suitable for production use.
 
 export type { WorkspaceEgressPolicy } from "../../runtime/egress.js";
 export {
diff --git a/packages/computer/src/backends/container/container-backend.ts b/packages/computer/src/backends/container/container-backend.ts
index ddf8f91e..ad5a546b 100644
--- a/packages/computer/src/backends/container/container-backend.ts
+++ b/packages/computer/src/backends/container/container-backend.ts
@@ -233,6 +233,12 @@ function bearerMatches(header: string | null, expected: string | undefined): boo
   return differences === 0;
 }
 
+/**
+ * Runs shell commands in a Cloudflare Container through `computerd`.
+ *
+ * Experimental: this API may change in any release and is not yet
+ * suitable for production use.
+ */
 export class ContainerBackend implements WorkspaceBackend {
   readonly type = "cloudflare-container";
   /** What this backend tells a model: a full Linux shell, its network access, and its slow start. */
diff --git a/packages/computer/src/backends/container/container-host.ts b/packages/computer/src/backends/container/container-host.ts
index dd4a7734..81f3d6c3 100644
--- a/packages/computer/src/backends/container/container-host.ts
+++ b/packages/computer/src/backends/container/container-host.ts
@@ -409,6 +409,12 @@ export type WithWorkspaceContainerCtor<TBase extends DOCtor> = TBase &
     ...args: any[]
   ) => InstanceType<TBase> & { getWorkspaceContainer(): WorkspaceContainerAPI });
 
+/**
+ * Adds the container host surface that `ContainerBackend` dials to a durable object class.
+ *
+ * Experimental: this API may change in any release and is not yet
+ * suitable for production use.
+ */
 export function withWorkspaceContainer<TBase extends DOCtor>(
   Base: TBase,
 ): WithWorkspaceContainerCtor<TBase> {
diff --git a/packages/computer/src/backends/container/index.ts b/packages/computer/src/backends/container/index.ts
index a1fa99dd..9e8088de 100644
--- a/packages/computer/src/backends/container/index.ts
+++ b/packages/computer/src/backends/container/index.ts
@@ -22,6 +22,9 @@
 //     ContainerBackend,
 //     withWorkspaceContainer,
 //   } from "@cloudflare/computer/backends/container";
+//
+// Status: experimental. This entry point may change in any release
+// and is not yet suitable for production use.
 
 export type { WorkspaceEgressPolicy } from "../../runtime/egress.js";
 export {
diff --git a/packages/computer/src/backends/worker-javascript/index.ts b/packages/computer/src/backends/worker-javascript/index.ts
index 41a4e81f..4ddd9da6 100644
--- a/packages/computer/src/backends/worker-javascript/index.ts
+++ b/packages/computer/src/backends/worker-javascript/index.ts
@@ -1,3 +1,10 @@
+// Public surface of @cloudflare/computer/backends/worker-javascript.
+//
+// WorkerJavaScriptBackend runs an ECMAScript module in a fresh Dynamic
+// Worker against the Workspace's files.
+//
+// Status: stable.
+
 export type { WorkspaceEgressPolicy } from "../../runtime/egress.js";
 export {
   WorkerJavaScriptBackend,
diff --git a/packages/computer/src/backends/worker-shell/index.ts b/packages/computer/src/backends/worker-shell/index.ts
index c9db0551..33bb6c64 100644
--- a/packages/computer/src/backends/worker-shell/index.ts
+++ b/packages/computer/src/backends/worker-shell/index.ts
@@ -1,4 +1,7 @@
-// Public surface of @cloudflare/computer/backends/worker.
+// Public surface of @cloudflare/computer/backends/worker-shell.
+//
+// Status: experimental. This entry point may change in any release
+// and is not yet suitable for production use.
 //
 // The worker backend pairs a Workspace with a just-bash shell
 // running in a Dynamic Worker minted through env.LOADER. Every
diff --git a/packages/computer/src/backends/worker-shell/worker-shell.ts b/packages/computer/src/backends/worker-shell/worker-shell.ts
index 1fe4a1b2..3a035c50 100644
--- a/packages/computer/src/backends/worker-shell/worker-shell.ts
+++ b/packages/computer/src/backends/worker-shell/worker-shell.ts
@@ -137,6 +137,12 @@ export interface WorkerShellBackendOptions {
 const DEFAULT_COMPAT_DATE = "2026-06-17";
 const DEFAULT_COMPAT_FLAGS = ["nodejs_compat"];
 
+/**
+ * Runs shell commands with just-bash in a Dynamic Worker.
+ *
+ * Experimental: this API may change in any release and is not yet
+ * suitable for production use.
+ */
 export class WorkerShellBackend implements WorkspaceBackend {
   readonly type = "worker-shell";
   /** What this backend tells a model: a fast shell with a fixed command set. */
diff --git a/packages/computer/src/index.ts b/packages/computer/src/index.ts
index 0de9a382..9a3f7e9e 100644
--- a/packages/computer/src/index.ts
+++ b/packages/computer/src/index.ts
@@ -14,6 +14,10 @@
 //
 // TestBackend stays on the main entry because it's a thin
 // test-only fake with no payload.
+//
+// Status: stable, except Workspace.push() and Workspace.pull(),
+// which drive the experimental sync with computerd. The package
+// README's status table is the canonical list.
 
 export type { SyncProgress } from "@cloudflare/computer-rpc/driver";
 export type {
diff --git a/packages/computerd/README.md b/packages/computerd/README.md
index 81766a35..d707f822 100644
--- a/packages/computerd/README.md
+++ b/packages/computerd/README.md
@@ -1,11 +1,11 @@
 # `@cloudflare/computerd`
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> **Experimental.** This package is provided for feedback only. Its APIs
+> may change in any release, and it is not suitable for production use
+> yet. Suitable for experiments, exploration, and prototypes. See the
+> [`@cloudflare/computer` status table](../computer/README.md#status)
+> for which components are stable.
 >
 > The specification under [`docs/`](../../docs/README.md) is forward-looking — read it for
 > intent, not as description of the code today.
diff --git a/packages/dofs/README.md b/packages/dofs/README.md
index e687bc2e..8130cadb 100644
--- a/packages/dofs/README.md
+++ b/packages/dofs/README.md
@@ -1,11 +1,14 @@
 # `@cloudflare/dofs`
 
-> [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> [!NOTE]
+> **Stable**, meaning suitable for production use, except the sync
+> protocol building blocks, which serve the experimental sync with
+> `computerd` and share its status. This package is not
+> published to npm on its own: it ships bundled inside
+> [`@cloudflare/computer`](../computer/README.md), which re-exports the
+> parts meant for callers. See that package's
+> [status table](../computer/README.md#status) for which components of
+> Cloudflare Computer are stable and which are experimental.
 >
 > The specification under [`docs/`](../../docs/README.md) is forward-looking — read it for
 > intent, not as description of the code today.
@@ -35,7 +38,7 @@ export class WorkspaceDO extends DurableObject {
 }
 ```
 
-> The `src/fs/*` primitives (`mkdir`, `writeFile`, `readFile`, `rm`, `readdir`, `stat`, `find`, `ls`, `grep`, `symlink`, `readlink`, `gc`, `watch`) are not re-exported from the package root yet — they are consumed in-tree by `SQLiteWorkspaceProvider` and by the sync `applyChanges` path. On the node side, instantiate `SQLiteWorkspaceProvider` (the `@platformatic/vfs` adapter) for a familiar node:fs-shaped surface; this is what `@cloudflare/computerd` mounts via FUSE. A higher-level DO-side `Workspace` class with the `fs`/`shell`/`push`/`pull` surface described in [`../../docs/README.md`](../../docs/README.md) is still future work.
+> The `src/fs/*` primitives (`mkdir`, `writeFile`, `readFile`, `rm`, `readdir`, `stat`, `find`, `ls`, `grep`, `symlink`, `readlink`, `gc`, `watch`) are not re-exported from the package root yet — they are consumed in-tree by `SQLiteWorkspaceProvider` and by the sync `applyChanges` path. On the node side, instantiate `SQLiteWorkspaceProvider` (the `@platformatic/vfs` adapter) for a familiar node:fs-shaped surface; this is what `@cloudflare/computerd` mounts via FUSE. The higher-level durable-object-side `Workspace` class described in [`../../docs/README.md`](../../docs/README.md) lives in [`@cloudflare/computer`](../computer/README.md).
 
 ## Implementation status
 
diff --git a/packages/dofs/src/index.ts b/packages/dofs/src/index.ts
index 0cf84460..20ddb1ba 100644
--- a/packages/dofs/src/index.ts
+++ b/packages/dofs/src/index.ts
@@ -1,3 +1,8 @@
+// Public surface of @cloudflare/dofs.
+//
+// Status: stable, except the sync protocol building blocks, which
+// serve the experimental sync with computerd.
+
 export type { WorkspaceErrorCode, WorkspaceFsError } from "./errors.js";
 export { createWorkspaceError } from "./errors.js";
 export { chmod } from "./fs/chmod.js";
diff --git a/packages/rpc/README.md b/packages/rpc/README.md
index 2109171a..bbcc6cb9 100644
--- a/packages/rpc/README.md
+++ b/packages/rpc/README.md
@@ -1,11 +1,11 @@
 # `@cloudflare/computer-rpc`
 
 > [!IMPORTANT]
-> **PREVIEW ONLY** This package is provided as a preview for feedback only.
-> APIs are unstable and the design is subject to change.
->
-> Suitable for experiments, exploration and prototypes. It is NOT suitable
-> for production use at this time.
+> **Experimental.** This package is provided for feedback only. Its APIs
+> may change in any release, and it is not suitable for production use
+> yet. Suitable for experiments, exploration, and prototypes. See the
+> [`@cloudflare/computer` status table](../computer/README.md#status)
+> for which components are stable.
 >
 > The specification under [`docs/`](../../docs/README.md) is forward-looking — read it for
 > intent, not as description of the code today.
diff --git a/packages/rpc/src/index.ts b/packages/rpc/src/index.ts
index 738c2c7e..5fcea313 100644
--- a/packages/rpc/src/index.ts
+++ b/packages/rpc/src/index.ts
@@ -1,5 +1,7 @@
 // Public surface of @cloudflare/computer-rpc.
 //
+// Status: experimental. The wire contract may change in any release.
+//
 // The package is split into four entry points:
 //
 //   - .          — the typed wire interface and error shape.

From 3ad51473cc8a8002fcf4d6dcc139552b0066c0ef Mon Sep 17 00:00:00 2001
From: Aron <263346377+aron-cf@users.noreply.github.com>
Date: Thu, 15 Oct 2026 12:40:09 +0100
Subject: [PATCH 2/5] Update stable-status.md

---
 .changeset/stable-status.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/stable-status.md b/.changeset/stable-status.md
index 51da6c8d..17c7aba2 100644
--- a/.changeset/stable-status.md
+++ b/.changeset/stable-status.md
@@ -2,4 +2,4 @@
 "@cloudflare/computer": patch
 ---
 
-Mark the `Workspace`, its filesystem, the worker-javascript backend, mounts, agent tools, Git, Assets, and Artifacts as stable; the container and worker-shell backends, `ws:container`, sync, and `computerd` stay experimental.
+`Workspace`, its filesystem, the worker-javascript backend, mounts, agent tools, Git, Assets, and Artifacts are now stable; the container and worker-shell backends, `ws:container`, sync, and `computerd` stay experimental.

From a8ec0c33caef07ccb558dc5e739667003c9fdf27 Mon Sep 17 00:00:00 2001
From: aron <263346377+aron-cf@users.noreply.github.com>
Date: Thu, 15 Oct 2026 13:43:40 +0100
Subject: [PATCH 3/5] computer, docs: Deprecate LegacyContainerBackend

LegacyContainerBackend serves containers the platform schedules from
the wrangler containers block. ContainerBackend serves containers the
durable object schedules itself, and is the backend new code should
use, so the legacy one is now deprecated rather than listed beside it
as an equal choice.

LegacyContainerBackend and withLegacyWorkspaceContainer carry a
@deprecated tag that names their replacements, so editors strike them
through. The status table and the backend table in the package README
mark the legacy backend deprecated and say what deprecated means. The
multiple-backends sample and the container links point at
ContainerBackend and examples/container. The entry point tables, the
injected service and Worker backend documents, and the examples that
still use the legacy backend say it is deprecated and name the
replacement.
---
 .changeset/stable-status.md                   |  2 +-
 README.md                                     |  3 ++-
 docs/07_injected_service.md                   |  5 +++--
 docs/12_worker_backend.md                     |  7 +++---
 docs/README.md                                |  2 +-
 examples/container-legacy/README.md           | 10 +++++----
 examples/egress/README.md                     |  4 +++-
 examples/tutorial/README.md                   |  3 ++-
 packages/computer/README.md                   | 22 +++++++++++++------
 .../container-legacy/cloudflare-container.ts  |  5 +++--
 .../container-legacy/container-host.ts        |  5 +++--
 .../src/backends/container-legacy/index.ts    |  4 ++--
 packages/computer/src/index.ts                |  4 ++--
 13 files changed, 47 insertions(+), 29 deletions(-)

diff --git a/.changeset/stable-status.md b/.changeset/stable-status.md
index 17c7aba2..5ba8542a 100644
--- a/.changeset/stable-status.md
+++ b/.changeset/stable-status.md
@@ -2,4 +2,4 @@
 "@cloudflare/computer": patch
 ---
 
-`Workspace`, its filesystem, the worker-javascript backend, mounts, agent tools, Git, Assets, and Artifacts are now stable; the container and worker-shell backends, `ws:container`, sync, and `computerd` stay experimental.
+`Workspace`, its filesystem, the worker-javascript backend, mounts, agent tools, Git, Assets, and Artifacts are now stable; `LegacyContainerBackend` is deprecated in favor of `ContainerBackend`; the container and worker-shell backends, `ws:container`, sync, and `computerd` stay experimental.
diff --git a/README.md b/README.md
index fabe8985..dd601d14 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,8 @@ public surface. Each is a Worker workspace with its own README.
   `scheduling_policy: "durable_object"` moves both out of the config.
 - [`examples/container-legacy`](examples/container-legacy) — the same
   surface against a container the platform schedules and sizes from the
-  `containers` block.
+  `containers` block. Uses the deprecated legacy container backend; new
+  code should follow `examples/container`.
 - [`examples/worker-shell`](examples/worker-shell) — same HTTP surface as the
   container example, but the shell runs [just-bash](https://github.com/vercel-labs/just-bash)
   in a Dynamic Worker loaded through `env.LOADER`. No container.
diff --git a/docs/07_injected_service.md b/docs/07_injected_service.md
index 9e715fef..3ae6b18a 100644
--- a/docs/07_injected_service.md
+++ b/docs/07_injected_service.md
@@ -1,7 +1,7 @@
 # 07. Injected Service
 
 > [!WARNING]
-> **Experimental.** `computerd` and the container backends may change in any release and
+> **Experimental.** `computerd` and the container backend may change in any release and
 > is not yet suitable for production use. See the
 > [status table](../packages/computer/README.md#status).
 
@@ -132,7 +132,8 @@ an `images` map. Each launch selects an image from
 pass options such as `entrypoint`, `labels`, and snapshot settings to
 `container.start()`.
 
-`LegacyContainerBackend` works with containers that the platform schedules.
+`LegacyContainerBackend` is deprecated; use `ContainerBackend` for new
+code. It works with containers that the platform schedules.
 The containers block chooses the image and instance size, so this backend
 passes only the environment and internet setting when it starts the
 container.
diff --git a/docs/12_worker_backend.md b/docs/12_worker_backend.md
index a2026e38..dbe85835 100644
--- a/docs/12_worker_backend.md
+++ b/docs/12_worker_backend.md
@@ -30,9 +30,10 @@ import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
 The primary container backend (`@cloudflare/computer/backends/container`)
 gives you a real Linux environment with arbitrary binaries on `$PATH`,
 optional network access, and a full POSIX filesystem. It costs a container
-per session and a real roundtrip on every filesystem operation. Use
-`@cloudflare/computer/backends/container-legacy` instead when the platform
-schedules and sizes the container.
+per session and a real roundtrip on every filesystem operation. The
+deprecated `@cloudflare/computer/backends/container-legacy` serves
+containers the platform schedules and sizes; new code should use the
+primary container backend.
 
 The worker backend trades the real environment for a Workers
 isolate that boots instantly, scales out cheaply, and has no
diff --git a/docs/README.md b/docs/README.md
index 04f1d938..49fbcd82 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -47,7 +47,7 @@ The package ships several entrypoints:
 | --- | --- |
 | `@cloudflare/computer` | The Workspace wrapper, first-class `workspace.runtime`, stub types, the R2 and Worker bundle mounts, and proxy classes. |
 | `@cloudflare/computer/backends/container` | `ContainerBackend` and `withWorkspaceContainer`, for a container the durable object schedules (`scheduling_policy: "durable_object"`). Same sync plumbing; the launch names the image and the instance size. |
-| `@cloudflare/computer/backends/container-legacy` | `LegacyContainerBackend` and `withLegacyWorkspaceContainer`, for a container the platform schedules and sizes from the containers block. |
+| `@cloudflare/computer/backends/container-legacy` | Deprecated; use `@cloudflare/computer/backends/container`. `LegacyContainerBackend` and `withLegacyWorkspaceContainer`, for a container the platform schedules and sizes from the containers block. |
 | `@cloudflare/computer/backends/worker-shell` | `WorkerShellBackend` and the bundled just-bash command runtime. |
 | `@cloudflare/computer/backends/worker-javascript` | `WorkerJavaScriptBackend`, configured libraries, durable relative imports, `node:fs/promises`, and host modules. |
 | `@cloudflare/computer/git` | Opt-in isomorphic-git glue for working with checkouts inside the workspace. Bundled lazily, with `pako` replaced by Workers `node:zlib`, and kept out of the default `@cloudflare/computer` graph. |
diff --git a/examples/container-legacy/README.md b/examples/container-legacy/README.md
index 36736794..be55a523 100644
--- a/examples/container-legacy/README.md
+++ b/examples/container-legacy/README.md
@@ -1,9 +1,11 @@
 # container example
 
-> [!IMPORTANT]
-> This example uses experimental parts of Cloudflare Computer: the legacy container backend and `computerd`.
-> Their APIs may change in any release, and they are not yet suitable
-> for production use. See the
+> [!WARNING]
+> This example uses the legacy container backend, which is deprecated.
+> New code should use `ContainerBackend`, shown in
+> [`examples/container`](../container). It also uses `computerd`, which
+> is experimental: its APIs may change in any release, and it is not yet
+> suitable for production use. See the
 > [status table](../../packages/computer/README.md#status).
 
 A Cloudflare Worker + Durable Object that boots a Container running
diff --git a/examples/egress/README.md b/examples/egress/README.md
index a55633aa..b8c7a432 100644
--- a/examples/egress/README.md
+++ b/examples/egress/README.md
@@ -1,7 +1,9 @@
 # egress example
 
 > [!IMPORTANT]
-> This example uses experimental parts of Cloudflare Computer: the container and Worker shell backends and `computerd`.
+> This example uses experimental parts of Cloudflare Computer: the Worker
+> shell backend and `computerd`. Its container path uses the deprecated
+> legacy container backend; new code should use `ContainerBackend`.
 > Their APIs may change in any release, and they are not yet suitable
 > for production use. See the
 > [status table](../../packages/computer/README.md#status).
diff --git a/examples/tutorial/README.md b/examples/tutorial/README.md
index 8c6aea84..ff9903de 100644
--- a/examples/tutorial/README.md
+++ b/examples/tutorial/README.md
@@ -1,7 +1,8 @@
 # Tutorial: a PDF recipe card agent
 
 > [!IMPORTANT]
-> This example uses experimental parts of Cloudflare Computer: the legacy container backend and `computerd`.
+> This example uses the deprecated legacy container backend and the
+> experimental `computerd`. New code should use `ContainerBackend`.
 > Their APIs may change in any release, and they are not yet suitable
 > for production use. See the
 > [status table](../../packages/computer/README.md#status).
diff --git a/packages/computer/README.md b/packages/computer/README.md
index e90144cd..7df00444 100644
--- a/packages/computer/README.md
+++ b/packages/computer/README.md
@@ -15,7 +15,8 @@ things in it.
 
 Stable means suitable for production use. Experimental APIs are
 provided for feedback: they may change or go away in any release, so
-use them for experiments and prototypes only.
+use them for experiments and prototypes only. Deprecated APIs will be
+removed in a future release; each one names its replacement.
 
 | Component | Entrypoint | Status |
 | --- | --- | --- |
@@ -29,7 +30,7 @@ use them for experiments and prototypes only.
 | Assets and Artifacts | `@cloudflare/computer/assets`, `@cloudflare/computer/artifacts` | Stable |
 | Observability hook and its Cloudflare adapter | `@cloudflare/computer`, `@cloudflare/computer/observe/cloudflare` | Stable |
 | `ContainerBackend` and `withWorkspaceContainer` | `@cloudflare/computer/backends/container` | Experimental |
-| `LegacyContainerBackend` and `withLegacyWorkspaceContainer` | `@cloudflare/computer/backends/container-legacy` | Experimental |
+| `LegacyContainerBackend` and `withLegacyWorkspaceContainer` | `@cloudflare/computer/backends/container-legacy` | Deprecated: use `ContainerBackend` |
 | `WorkerShellBackend` and the shell command groups | `@cloudflare/computer/backends/worker-shell`, `@cloudflare/computer/shell/*` | Experimental |
 | The `ws:container` host module | `@cloudflare/computer/modules/container` | Experimental |
 | `workspace.push()`, `workspace.pull()`, and the sync protocol between the durable object and `computerd` | `@cloudflare/computer` | Experimental |
@@ -312,7 +313,7 @@ Alongside `exec`, the runtime exposes `getExec`, `killExec`, and
 | Backend | Status | Import | Runs | Needs |
 | --- | --- | --- | --- | --- |
 | **Container** | Experimental | `@cloudflare/computer/backends/container` | Shell commands in full Linux userland (real binaries, `npm`, `node`, network) | A Cloudflare Container running `computerd`, scheduled by the durable object (`scheduling_policy: "durable_object"`) |
-| **Container (legacy)** | Experimental | `@cloudflare/computer/backends/container-legacy` | The same | A Cloudflare Container the platform schedules and sizes from the `containers` block |
+| **Container (legacy)** | Deprecated | `@cloudflare/computer/backends/container-legacy` | The same | A Cloudflare Container the platform schedules and sizes from the `containers` block |
 | **Worker shell** | Experimental | `@cloudflare/computer/backends/worker-shell` | Shell commands via [just-bash](https://github.com/vercel-labs/just-bash) in a Dynamic Worker | A Worker Loader binding; `experimental` flag |
 | **Worker JavaScript** | Stable | `@cloudflare/computer/backends/worker-javascript` | ECMAScript modules in a fresh Dynamic Worker | A Worker Loader binding |
 
@@ -320,7 +321,11 @@ Alongside `exec`, the runtime exposes `getExec`, `killExec`, and
   environment. The container owns its own SQLite-backed VFS and this
   package syncs the two stores across a capnweb WebSocket. See
   [`docs/07_injected_service.md`](../../docs/07_injected_service.md) for
-  the container image, and [`examples/container-legacy`](../../examples/container-legacy).
+  the container image, and [`examples/container`](../../examples/container).
+- **Container (legacy)** is deprecated. It serves containers the
+  platform schedules from the `containers` block. Move to the container
+  backend, which needs `scheduling_policy: "durable_object"` and an
+  `images` map instead.
 - **Worker shell** is fast and needs no container. Every filesystem
   operation forwards back to the same Durable Object, so there's no
   second store and no sync round trip. See
@@ -500,7 +505,8 @@ on a computerd instance.
 | Entrypoint | Purpose |
 | --- | --- |
 | `@cloudflare/computer` | The `Workspace` wrapper, `workspace.runtime`, stub types, the R2 and Worker bundle mounts, and proxy classes. |
-| `@cloudflare/computer/backends/container-legacy` | `LegacyContainerBackend` and `withLegacyWorkspaceContainer`. Pulls in the computerd / capnweb sync plumbing. |
+| `@cloudflare/computer/backends/container` | `ContainerBackend` and `withWorkspaceContainer`. Pulls in the computerd / capnweb sync plumbing. |
+| `@cloudflare/computer/backends/container-legacy` | Deprecated. `LegacyContainerBackend` and `withLegacyWorkspaceContainer`; use `@cloudflare/computer/backends/container` instead. |
 | `@cloudflare/computer/backends/worker-shell` | `WorkerShellBackend` and the bundled just-bash runtime. |
 | `@cloudflare/computer/backends/worker-javascript` | `WorkerJavaScriptBackend`, configured libraries, durable imports, `node:fs/promises`, and host modules. |
 | `@cloudflare/computer/modules/container` | `createContainerModule()` for `ws:container`: run container commands from isolate JavaScript. |
@@ -539,7 +545,7 @@ const ws = new Workspace({
   storage: ctx.storage,
   backends: [
     new WorkerShellBackend({ id: "shell", loader: env.LOADER, /* ... */ }),
-    new LegacyContainerBackend({ id: "sandbox", container: () => this, /* ... */ }),
+    new ContainerBackend({ id: "sandbox", container: () => this, /* ... */ }),
   ],
 });
 
@@ -604,8 +610,10 @@ An adapter for the Cloudflare runtime lives at
   No container.
 - [`examples/worker-javascript`](../../examples/worker-javascript) — the
   same shape, running ECMAScript modules instead of shell commands.
-- [`examples/container-legacy`](../../examples/container-legacy) — the container
+- [`examples/container`](../../examples/container) — the container
   backend running `computerd`.
+- [`examples/container-legacy`](../../examples/container-legacy) — the
+  deprecated legacy container backend.
 - [`examples/think`](../../examples/think) — a chat agent that uses the
   workspace as its working directory.
 - [`examples/tutorial`](../../examples/tutorial) — a step-by-step build:
diff --git a/packages/computer/src/backends/container-legacy/cloudflare-container.ts b/packages/computer/src/backends/container-legacy/cloudflare-container.ts
index d22af393..29d91837 100644
--- a/packages/computer/src/backends/container-legacy/cloudflare-container.ts
+++ b/packages/computer/src/backends/container-legacy/cloudflare-container.ts
@@ -181,8 +181,9 @@ function bearerMatches(header: string | null, expected: string | undefined): boo
 /**
  * Runs shell commands in a platform-scheduled Cloudflare Container through `computerd`.
  *
- * Experimental: this API may change in any release and is not yet
- * suitable for production use.
+ * @deprecated Use `ContainerBackend` from
+ * `@cloudflare/computer/backends/container`, which serves containers the
+ * durable object schedules. This backend will be removed in a future release.
  */
 export class LegacyContainerBackend implements WorkspaceBackend {
   readonly type = "cloudflare-container";
diff --git a/packages/computer/src/backends/container-legacy/container-host.ts b/packages/computer/src/backends/container-legacy/container-host.ts
index 9d46147f..bd51127b 100644
--- a/packages/computer/src/backends/container-legacy/container-host.ts
+++ b/packages/computer/src/backends/container-legacy/container-host.ts
@@ -348,8 +348,9 @@ export type WithWorkspaceContainerCtor<TBase extends DOCtor> = TBase &
 /**
  * Adds the container host surface that `LegacyContainerBackend` dials to a durable object class.
  *
- * Experimental: this API may change in any release and is not yet
- * suitable for production use.
+ * @deprecated Use `withWorkspaceContainer` from
+ * `@cloudflare/computer/backends/container`. This mixin will be removed in
+ * a future release.
  */
 export function withLegacyWorkspaceContainer<TBase extends DOCtor>(
   Base: TBase,
diff --git a/packages/computer/src/backends/container-legacy/index.ts b/packages/computer/src/backends/container-legacy/index.ts
index 88adf749..729cea6a 100644
--- a/packages/computer/src/backends/container-legacy/index.ts
+++ b/packages/computer/src/backends/container-legacy/index.ts
@@ -27,8 +27,8 @@
 //     withLegacyWorkspaceContainer,
 //   } from "@cloudflare/computer/backends/container-legacy";
 //
-// Status: experimental. This entry point may change in any release
-// and is not yet suitable for production use.
+// Status: deprecated. Use @cloudflare/computer/backends/container
+// instead; this entry point will be removed in a future release.
 
 export type { WorkspaceEgressPolicy } from "../../runtime/egress.js";
 export {
diff --git a/packages/computer/src/index.ts b/packages/computer/src/index.ts
index 9a3f7e9e..2910db30 100644
--- a/packages/computer/src/index.ts
+++ b/packages/computer/src/index.ts
@@ -9,8 +9,8 @@
 // backend, etc.) can be tree-shaken when a consumer only uses
 // one of them:
 //
-//   import { LegacyContainerBackend } from "@cloudflare/computer/backends/container-legacy";
-//   import { WorkerShellBackend }         from "@cloudflare/computer/backends/worker-shell";
+//   import { ContainerBackend }   from "@cloudflare/computer/backends/container";
+//   import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
 //
 // TestBackend stays on the main entry because it's a thin
 // test-only fake with no payload.

From 4e29c0d28e2f0df7c262eb5c086066a5406df098 Mon Sep 17 00:00:00 2001
From: aron <263346377+aron-cf@users.noreply.github.com>
Date: Thu, 15 Oct 2026 13:43:40 +0100
Subject: [PATCH 4/5] docs: List experimental and deprecated code in
 SECURITY.md

The security policy said parts of Cloudflare Computer are experimental
but left a reader to work out which code that means. It now lists the
directories and files that hold experimental code, the deprecated
legacy container backend, and the directories that are not part of any
published package, such as examples and test harnesses.
---
 .github/SECURITY.md | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/.github/SECURITY.md b/.github/SECURITY.md
index 9585bfb7..c0c1de2d 100644
--- a/.github/SECURITY.md
+++ b/.github/SECURITY.md
@@ -1,6 +1,35 @@
 # Security Policy
 
 > [!IMPORTANT]
-> Parts of Cloudflare Computer are stable and parts are experimental. Most of it is stable. The container backends, the Worker shell backend, the `ws:container` host module, the sync between the durable object and `computerd`, `computerd` itself, and the RPC package are experimental and under active development; the [status table](../packages/computer/README.md#status) has the full list. Do not rely on the experimental components for production security guarantees.
-> 
-> Reporting a security issue: If you find what you believe to be a security issue, please open a GitHub issue in this repository describing it. 
+> Most of Cloudflare Computer is stable, meaning suitable for production use. The parts listed below are experimental or deprecated. Do not rely on them for production security guarantees. The [status table](../packages/computer/README.md#status) describes the same split by API.
+>
+> Reporting a security issue: If you find what you believe to be a security issue, please open a GitHub issue in this repository describing it.
+
+## Experimental code
+
+These directories and files hold experimental code:
+
+- `packages/computerd/`: the `computerd` daemon and its FUSE mount.
+- `packages/computer-computerd-linux-x64/`: the `computerd` container image.
+- `packages/rpc/`: the RPC wire protocol between the durable object and `computerd`.
+- `packages/computer/src/backends/container/`: the container backend.
+- `packages/computer/src/backends/worker-shell/`: the Worker shell backend and its shell command groups.
+- `packages/computer/src/modules/container.ts`: the `ws:container` host module.
+- `packages/dofs/src/sync/`: the sync protocol building blocks.
+- `packages/dofs/src/schema/sync.ts`: the tables that hold sync state.
+
+`workspace.push()` and `workspace.pull()` in `packages/computer/src/workspace.ts` drive the sync with `computerd`, so they are experimental too, even though the rest of that file is stable.
+
+## Deprecated code
+
+These directories hold deprecated code, which will be removed in a future release:
+
+- `packages/computer/src/backends/container-legacy/`: the legacy container backend. Use `packages/computer/src/backends/container/` instead.
+
+## Code that is not shipped
+
+These directories are not part of any published package, so they carry no stability or security guarantees:
+
+- `examples/`: example Workers. Each example's README says which experimental parts it uses.
+- `script/`: maintenance scripts and test harnesses.
+- `packages/computer/test-harness/`, `packages/computer/src/test-harness/`, `packages/computer/tests/`, and `packages/computer/test-helpers/`: test code.

From e93d3ba76512acc00531fd5c46cb0276002e3be4 Mon Sep 17 00:00:00 2001
From: aron <263346377+aron-cf@users.noreply.github.com>
Date: Thu, 15 Oct 2026 13:43:40 +0100
Subject: [PATCH 5/5] docs: Reword the status notes at the top of the READMEs

The notes at the top of the repository, package, and specification
READMEs listed each experimental component. They now say that
@cloudflare/computer is suitable for production use, that it contains
work-in-progress and experimental components such as ContainerBackend
that are not, and point to the package's status table, which remains
the full list.
---
 README.md                   | 15 ++++-----------
 docs/README.md              | 12 ++++--------
 packages/computer/README.md |  8 ++++----
 3 files changed, 12 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index dd601d14..5fef1db0 100644
--- a/README.md
+++ b/README.md
@@ -26,17 +26,10 @@ Workspace can also be constructed without a backend at all, giving
 callers the filesystem on its own.
 
 > [!IMPORTANT]
-> Most of Cloudflare Computer is stable, meaning suitable for
-> production use: the `Workspace`, its SQLite filesystem
-> (`@cloudflare/dofs`), the Isolate JavaScript backend, mounts, agent
-> tools, Git, Assets, and Artifacts.
->
-> The experimental parts are the container backends, the Worker shell backend, the `ws:container`
-> host module, the sync between the durable object and `computerd`,
-> `computerd` itself, and the RPC package. Their APIs
-> may change in any release, and they are not yet suitable for production
-> use. The [`@cloudflare/computer` status table](packages/computer/README.md#status)
-> has the full list.
+> The `@cloudflare/computer` package should be considered suitable for
+> production use. The package contains work-in-progress and experimental
+> components such as the `ContainerBackend`. These should be considered
+> unsuitable for production use. See the [status reference](packages/computer/README.md#status) for more details.
 >
 > The specification under [`docs/`](docs/) is forward-looking — read it for
 > intent, not as description of the code today.
diff --git a/docs/README.md b/docs/README.md
index 49fbcd82..de0923be 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,14 +1,10 @@
 # `@cloudflare/computer`
 
 > [!IMPORTANT]
-> Most of Cloudflare Computer is stable, meaning suitable for
-> production use. The experimental parts are the container backends, the Worker shell backend, the `ws:container`
-> host module, the sync between the durable object and `computerd`,
-> `computerd` itself, and the RPC package. Their APIs
-> may change in any release, and they are not yet suitable for production
-> use. The topic index below marks each document's status, and the
-> [`@cloudflare/computer` status table](../packages/computer/README.md#status)
-> has the full list.
+> The `@cloudflare/computer` package should be considered suitable for
+> production use. The package contains work-in-progress and experimental
+> components such as the `ContainerBackend`. These should be considered
+> unsuitable for production use. See the [status reference](../packages/computer/README.md#status) for more details.
 >
 > The specification in this directory is forward-looking — read it for
 > intent, not as description of the code today.
diff --git a/packages/computer/README.md b/packages/computer/README.md
index 7df00444..7ba5d76f 100644
--- a/packages/computer/README.md
+++ b/packages/computer/README.md
@@ -6,10 +6,10 @@ small, portable working directory and the tools to read, write, and run
 things in it.
 
 > [!IMPORTANT]
-> Most of this package is stable. The container backends, the Worker
-> shell backend, the `ws:container` host module, the sync between the
-> durable object and `computerd`, and `computerd` itself are
-> experimental. See [Status](#status) for the full list.
+> The `@cloudflare/computer` package should be considered suitable for
+> production use. The package contains work-in-progress and experimental
+> components such as the `ContainerBackend`. These should be considered
+> unsuitable for production use. See the [reference below](#status) for more details.
 
 ## Status