docs: update Workers Previews documentation

src/content/docs/workers/ci-cd/builds/build-branches.mdx

@@ -25,6 +25,8 @@ Every push event made to this branch will trigger a build and execute the [build
 
 Preview builds are builds for branches that are not your production branch.
 
+New Workers use Worker Previews for preview builds by default. Their Preview command is `npx wrangler preview`.
+
 To enable or disable preview builds:
 
 1. In **Overview**, select your Workers project.
@@ -34,13 +36,21 @@ When enabled, every push to a branch that is not your production branch triggers
 
 ### Existing Workers connected to Builds
 
+Workers that were connected to Builds before [Worker Previews](/workers/previews/) keep the previous preview model until you complete a one-time switch.
+
+:::caution[The switch cannot be reversed]
+After switching, you cannot return to the previous preview model, which uses production settings.
+:::
+
 <Steps>
 1. In the Cloudflare dashboard, go to **Workers & Pages** > your Worker > **Settings** > **Builds**. In the **Set up Worker Previews** banner, select **Set up**.
 
    <DashButton url="/?to=/:account/workers-and-pages" />
 
-2. Confirm that you configured Preview variables, secrets, and bindings. For setup instructions, refer to [Get started](/workers/previews/get-started/#step-1-configure-preview-settings).
-3. Review the new Preview command. Custom commands must invoke `npx wrangler preview`.
+   ![Dialog showing Preview settings confirmation and the new Worker Previews command](~/assets/images/workers/ci-cd/builds/switch-to-worker-previews.png)
+
+2. Configure the variables, secrets, and bindings your Worker needs for Previews. Previews do not use production settings. For instructions, refer to [Get started](/workers/previews/get-started/#step-1-configure-preview-settings).
+3. Review the new Preview command. Workers Builds replaces the current command with `npx wrangler preview`. Custom commands must invoke `npx wrangler preview`.
 4. Select **Switch to Worker Previews**.
 </Steps>
 

src/content/docs/workers/previews/compare-workflows.mdx

@@ -8,37 +8,23 @@ products:
   - workers
 ---
 
-For non-production testing, use Previews. Previews give every branch its own isolated copy of your Worker with Preview-specific variables, secrets, bindings, and isolation for supported resources.
-
-Version URLs and Wrangler environments still exist, but they solve narrower problems. This page explains when each one applies and why Previews should be your default.
-
-## Quick comparison
-
-| Workflow                  | Best for                                                          | Command                        | Resource behavior                                                                                     |
-| ------------------------- | ----------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| **Previews**              | Branches and pull requests.                                       | `npx wrangler preview`         | Can use Preview-specific variables, secrets, and bindings. Some resources are isolated automatically. |
-| **Version URLs**          | Inspecting one uploaded Worker version.                           | `wrangler versions upload`     | Uses the resources configured for that Worker version. Does not create branch-isolated resources.     |
-| **Wrangler environments** | Persistent environments like staging, development, or production. | `wrangler deploy --env <name>` | Creates a separately named Worker with environment-specific config.                                   |
-
-## Previews
+import { WranglerConfig } from "~/components";
 
 Previews are the recommended way to test changes before production.
 
-Your production branch uses `wrangler deploy`. Your feature branch uses `npx wrangler preview`. The Preview gets a stable Preview URL with its own variables, secrets, and bindings.
-
-Use Previews for:
+## Quick comparison
 
-- Pull request and branch review.
-- QA and stakeholder testing.
-- Testing with Preview-specific resources, such as test databases, staging KV namespaces, and separate Durable Object storage.
-- Sharing custom domain Preview URLs.
-- Any workflow where you previously used Version URL aliases or Wrangler environments for branch testing.
+| Workflow                                                            | Best for                                                                | Command                        |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------ |
+| **Previews**                                                        | Full environments for branches and pull requests under the same Worker. | `npx wrangler preview`         |
+| **[Version URLs](/workers/versions-and-deployments/version-urls/)** | An uploaded version of your code that uses production resources.        | `wrangler versions upload`     |
+| **[Wrangler environments](/workers/wrangler/environments/)**        | Separately deployed Workers.                                            | `wrangler deploy --env <name>` |
 
 ## Version URLs
 
-:::caution[Version URLs use the version's resources]
+:::caution[Version URLs use production resources]
 
-A Version URL runs one uploaded Worker version. It uses the resources configured for that Worker version. It does not create isolated branch resources.
+A Version URL runs one uploaded Worker version with the production resources configured for that version. It does not create isolated branch resources.
 
 Do not use Version URLs for branch or pull request testing. Use [Previews](/workers/previews/) instead.
 
@@ -67,13 +53,57 @@ Previews give you branch isolation, Preview-specific settings, custom domain sup
 
 ## Wrangler environments
 
-Wrangler environments create separately named Workers, such as `my-worker-staging`, deployed with `wrangler deploy --env staging`. They are not created automatically for branches or pull requests.
+Wrangler environments create separately named Workers, such as `my-worker-staging`. Use them when development, staging, or other environments need persistent Workers with different settings, routes, or custom domains.
+
+You can create branch Previews under a Wrangler environment. Define its Preview settings in `env.staging.previews`:
+
+<WranglerConfig>
 
-If you are using Wrangler environments for branch or pull request testing, switch to Previews. Previews handle branch isolation automatically and do not require manually maintaining separate environment blocks with duplicated bindings.
+```jsonc
+{
+  "name": "my-worker",
+  "env": {
+    "dev": {
+      "name": "my-worker-dev",
+      "vars": {
+        "ENVIRONMENT": "development"
+      }
+    },
+    "staging": {
+      "name": "my-worker-staging",
+      "vars": {
+        "ENVIRONMENT": "staging"
+      },
+      "previews": {
+        "vars": {
+          "ENVIRONMENT": "staging-preview"
+        }
+      }
+    }
+  }
+}
+```
 
-Wrangler environments are still useful for:
+</WranglerConfig>
 
-- Long-lived persistent environments that must always be running, for example, a staging Worker that external partners hit continuously.
-- Environment-specific routes or custom domains that need to stay up permanently.
+In this example, `dev` has no `previews` block and remains a persistent Worker environment. `staging` includes a `previews` block for branch Previews.
 
-For most teams, Previews replace the need for a `[env.staging]` or `[env.dev]` block entirely. You do not need to create a Wrangler environment to use Previews.
+Then include the environment when you run the Preview command:
+
+```sh
+npx wrangler preview --env staging
+```
+
+This creates or updates the branch Preview under the staging Worker. The Wrangler environment provides the persistent boundary, and Previews provide branch isolation within it.
+
+:::caution[Include the environment in every Preview command]
+
+Use the same `--env` value when you create, update, manage, or delete a Preview. For example:
+
+```sh
+npx wrangler preview delete --env staging --name <PREVIEW_NAME>
+```
+
+If you omit `--env staging`, Wrangler targets the top-level Worker instead of the staging Worker.
+
+:::

src/content/docs/workers/previews/configuration.mdx

@@ -15,7 +15,7 @@ Previews do not inherit production settings. Define them in the [`previews` bloc
 
 ## Setting your Previews Base configuration
 
-Define your starting `previews` block on the branch your team branches from, such as `main`. Git carries the configuration file into each new branch, so you do not need to redefine Preview settings every time.
+Define your starting `previews` block on the branch your team branches from, such as `main`. Git carries the configuration file into each new branch.
 
 Change the `previews` block on a branch when its Preview needs different settings. When you run `npx wrangler preview`, Wrangler uses the configuration file from your current branch as the source of truth. For setup instructions, refer to [Get started](/workers/previews/get-started/).
 
@@ -149,11 +149,9 @@ Do not add Queue consumers, Cron Triggers, or production routes to `previews`. T
 
 Service bindings from a Preview call the bound Worker's production deployment. For more limitations, refer to [Limitations](/workers/previews/resources/#limitations).
 
-## Dashboard
+## Dashboard configuration
 
-Configure Previews Base settings in the dashboard. When you add or change a setting, the dashboard shows the matching `previews` configuration to add to your Wrangler file. Copy those changes into your file to keep future deployments in sync.
-
-![Dashboard showing generated Wrangler configuration for a Previews Base binding](~/assets/images/workers/previews/dashboard-wrangler-config.png)
+You can configure Previews Base settings in the dashboard, but you must copy the generated configuration into your Wrangler file. To avoid this extra step, configure your Preview settings in the Wrangler file directly.
 
 <Steps>
 1. In the Cloudflare dashboard, go to **Workers & Pages**.
@@ -168,4 +166,8 @@ Configure Previews Base settings in the dashboard. When you add or change a sett
 4. Select **Previews Base** in each section to configure what new Previews start from. You can import names and values from production, then edit them. You must re-enter secrets manually.
 
    ![Import dialog showing variables and secrets imported from production to Previews](~/assets/images/workers/previews/import_from_prod.png)
+
+5. Update your Wrangler configuration file with the generated `previews` configuration. This keeps future deployments in sync.
+
+   ![Dashboard showing generated Wrangler configuration for a Previews Base binding](~/assets/images/workers/previews/dashboard-wrangler-config.png)
 </Steps>

src/content/docs/workers/previews/custom-domains.mdx

@@ -8,62 +8,38 @@ products:
   - workers
 ---
 
-import { DashButton, Steps, TabItem, Tabs, WranglerConfig } from "~/components";
-
-**Before you start:** For custom domains, enable Previews in the same place that manages the domain. If the Cloudflare dashboard manages it, use the Dashboard instructions. If Wrangler or Terraform manages it, enable Previews in that configuration so the next deploy does not overwrite dashboard changes.
-
-Preview URLs can be served from a custom domain, from `workers.dev`, or from both.
-
-| Host type     | Preview URL                                            | Deployment URL                                          |
+import {
+	DashButton,
+	Details,
+	Steps,
+	TabItem,
+	Tabs,
+	WranglerConfig,
+} from "~/components";
+
+Preview URLs can use a custom domain, `workers.dev`, or both. Enable at least one host to get a Preview URL.
+
+| Host          | Preview URL                                            | Unique deployment URL                                   |
 | ------------- | ------------------------------------------------------ | ------------------------------------------------------- |
 | Custom domain | `<preview-name>.app.example.com`                       | `<deployment-id>-<preview-name>.app.example.com`        |
 | `workers.dev` | `<preview-name>-<worker-name>.<subdomain>.workers.dev` | `<deployment-id>-<worker-name>.<subdomain>.workers.dev` |
 
-Enable at least one host type to get a Preview URL. If both [custom domain Preview URLs](#enable-custom-domain-previews) and [`workers.dev` Preview URLs](#enable-workersdev-previews) are disabled, your Preview will not have a URL to visit.
+## Before you start
 
-## Enable custom domain Previews
+Configure Previews in the same system that manages your custom domain:
 
-When you enable Previews on a custom domain, Cloudflare provisions a wildcard DNS record and SSL certificate, such as `*.app.example.com`. SSL certificates can take time to issue after the first Preview is created.
+| Managed with | Configuration                                             |
+| ------------ | --------------------------------------------------------- |
+| Wrangler     | Use the **Wrangler** tab, then run `npx wrangler deploy`. |
+| Dashboard    | Use the **Dashboard** tab.                                |
+| Terraform    | Update and apply your Terraform configuration.            |
 
-:::note[Use a dedicated subdomain]
-If your production domain already has subdomains like `docs.example.com`, use a dedicated Preview subdomain to avoid wildcard conflicts. It can be `previews.example.com`, `staging.example.com`, or another hostname you reserve for Previews.
-:::
+## Enable custom domain Preview URLs
 
 <Tabs syncKey="customDomainSetup">
-<TabItem label="Dashboard">
-
-<Steps>
-1. In the Cloudflare dashboard, go to **Workers & Pages**.
-
-   <DashButton url="/?to=/:account/workers-and-pages" />
-
-2. Select your Worker.
-3. Go to the **Domains** tab.
-4. Under **Custom Domains and Routes**, select **+ Add Domain**.
-
-   ![Domains tab showing workers.dev Preview URLs enabled with no custom domains configured](~/assets/images/workers/previews/emptydomain.png)
-
-   In this example, only the `workers.dev` Preview URL is enabled, so Preview traffic is served only on `workers.dev`.
-
-5. Enter your domain and optional subdomain. Set **Enable for** to _Preview_ to serve only Preview URLs on this domain, then select **Add domain**.
-
-   ![Add Domain modal with Enable for set to Preview](~/assets/images/workers/previews/replace.png)
-
-   You can also choose _Production and Preview_ to serve both production and Preview URLs on the same domain, or _Production_ for production traffic only.
-
-6. Confirm that your custom domain appears in **Custom Domains and Routes**.
-
-   ![Domains tab showing workers.dev URLs disabled and a custom domain enabled for Preview](~/assets/images/workers/previews/customdomainonly.png)
-
-   In this example, both `workers.dev` URLs are disabled. Preview traffic is served only on `previews.example.com`.
-</Steps>
-
-</TabItem>
 <TabItem label="Wrangler">
 
-Set `previews_enabled` on the custom domain route in your Wrangler configuration file, then run `npx wrangler deploy`.
-
-The custom domain Preview route is created during deploy and will not appear in the dashboard until the deploy completes.
+The following example configures `app.example.com` for Preview traffic only. Add `previews_enabled` and set `enabled` to `false`, then run `npx wrangler deploy` to apply the configuration.
 
 <WranglerConfig>
 
@@ -73,48 +49,57 @@ The custom domain Preview route is created during deploy and will not appear in
     {
       "pattern": "app.example.com",
       "custom_domain": true,
-      "previews_enabled": true
+      "previews_enabled": true,
+      "enabled": false
     }
   ]
 }
 ```
 
 </WranglerConfig>
 
-The custom domain itself still serves production traffic. Preview URLs are served on subdomains like `<preview-name>.app.example.com`.
-
-</TabItem>
-</Tabs>
-
-:::note[Certificate coverage for deeper subdomains]
-Preview URLs add another subdomain to the hostname you configure. For example, `app.preview.example.com` creates Preview URLs like `<preview-name>.app.preview.example.com`. If that hostname is not covered by your existing certificate, you may need [Advanced Certificate Manager](/ssl/edge-certificates/advanced-certificate-manager/) with [Total TLS](/ssl/edge-certificates/additional-options/total-tls/) or another certificate that covers the Preview hostname.
-:::
+Choose which traffic the custom domain serves:
 
-## Enable `workers.dev` Previews
+| Traffic                | `previews_enabled` | `enabled`        |
+| ---------------------- | ------------------ | ---------------- |
+| Preview only           | `true`             | `false`          |
+| Production and Preview | `true`             | Omit or set `true` |
 
-The `workers.dev` Production and Preview URLs are toggled separately. You do not need to enable `workers.dev` Preview URLs to use custom domain Previews.
-
-<Tabs syncKey="workersDevPreviewSetup">
+</TabItem>
 <TabItem label="Dashboard">
 
 <Steps>
-1. In the Cloudflare dashboard, go to **Workers & Pages**.
+1. In the Cloudflare dashboard, go to **Workers & Pages** and select your Worker.
 
    <DashButton url="/?to=/:account/workers-and-pages" />
 
-2. Select your Worker.
-3. Go to the **Domains** tab.
-4. Under **Worker URL**, toggle on the **Preview** URL (`*-<worker-name>.<subdomain>.workers.dev`).
+2. On the **Domains** tab, under **Custom Domains and Routes**, select **+ Add Domain**.
+3. Enter your domain. For **Enable for**, select _Preview_ or _Production and Preview_. Then select **Add domain**.
 
-   ![Domains tab showing workers.dev Preview URLs enabled with no custom domains configured](~/assets/images/workers/previews/emptydomain.png)
-
-   In this example, the production `workers.dev` URL is disabled, the Preview `workers.dev` URL is enabled, and no custom domains are configured.
+   ![Add Domain modal with Enable for set to Preview](~/assets/images/workers/previews/replace.png)
 </Steps>
 
 </TabItem>
+</Tabs>
+
+<Details header="DNS and certificate behavior">
+
+Cloudflare creates a wildcard DNS record and SSL certificate for the custom domain, such as `*.app.example.com`. Certificate issuance can take time after you create the first Preview.
+
+Use a dedicated hostname such as `previews.example.com` if your production domain already has subdomains. This avoids wildcard conflicts.
+
+Preview URLs add another subdomain to your hostname. For example, `app.preview.example.com` creates `<preview-name>.app.preview.example.com`. For deeper hostnames, you may need [Advanced Certificate Manager](/ssl/edge-certificates/advanced-certificate-manager/) with [Total TLS](/ssl/edge-certificates/additional-options/total-tls/) or another certificate that covers the Preview hostname.
+
+</Details>
+
+## Enable `workers.dev` Preview URLs
+
+Production and Preview `workers.dev` URLs are configured separately.
+
+<Tabs syncKey="workersDevPreviewSetup">
 <TabItem label="Wrangler">
 
-Set `preview_urls` in your Wrangler configuration file, then redeploy with `npx wrangler deploy`.
+Set `preview_urls` in your Wrangler configuration file, then run `npx wrangler deploy`.
 
 <WranglerConfig>
 
@@ -126,11 +111,24 @@ Set `preview_urls` in your Wrangler configuration file, then redeploy with `npx
 
 </WranglerConfig>
 
-If `preview_urls` is not specified, it defaults to the value of `workers_dev`. Disabling `workers_dev` does not disable Preview URLs if `preview_urls` is still enabled.
+If omitted, `preview_urls` uses the value of `workers_dev`. Set it explicitly to manage Production and Preview URLs separately.
+
+</TabItem>
+<TabItem label="Dashboard">
+
+<Steps>
+1. In the Cloudflare dashboard, go to **Workers & Pages** and select your Worker.
+
+   <DashButton url="/?to=/:account/workers-and-pages" />
+
+2. On the **Domains** tab, under **Worker URL**, turn on **Preview**.
+
+   ![Domains tab showing workers.dev Preview URLs enabled with no custom domains configured](~/assets/images/workers/previews/emptydomain.png)
+</Steps>
 
 </TabItem>
 </Tabs>
 
 ## Protect with Cloudflare Access
 
-Use [Cloudflare Access](/workers/configuration/cloudflare-access/) to require sign-in before visitors can reach a Preview URL. Configure Access for Previews in one place, whether the Preview URL uses `workers.dev` or a custom domain.
+Use [Cloudflare Access](/workers/configuration/cloudflare-access/) to require sign-in for custom domain and `workers.dev` Preview URLs.