From ad361ab05d81287bdf187ff474297198bed033e8 Mon Sep 17 00:00:00 2001
From: micheleRP <michele@redpanda.com>
Date: Mon, 20 Jul 2026 17:22:40 -0600
Subject: [PATCH 1/2] DOC-1860: Cluster sizing, tier migration, and user
 scaling GA docs

Consolidated doc update for the cluster sizing and scaling initiative
(DOC-1860, DOC-1375, DOC-940, DOC-1861 provisioning half; DOC-1133 API
section stubbed for separate ownership):

- manage/maintenance.adoc: new Tier migrations section (DOC-1375)
- reference/partials/tiers.adoc: guidance (up to) framing and machine
  types/RPU concept for BYOC tiers (DOC-940)
- get-started/.../byoc/size-byoc-cluster.adoc: new page for the
  workload-based sizing and pricing calculator, UI + Control Plane API
  (DOC-1861)
- manage/cluster-maintenance/scale-cluster.adoc: new page for
  self-service horizontal/vertical scaling, prepared for user scaling
  GA (DOC-1860, ENG-928); merge with the GA release
- BYOC create pages: pointer to workload-based sizing
- terraform-provider.adoc: tier-migration cross-link and GA revision
  note for the throughput_tier warning
- whats-new-cloud.adoc: scaling GA entry under a placeholder month;
  sizing calculator entry drafted in a comment pending rollout
  confirmation

TODO(eng)/TODO(ux)/TODO(api) comments mark items to verify before
merge. Keep the PR in draft until ENG-928 ships.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 modules/ROOT/nav.adoc                         |  2 +
 .../byoc/aws/create-byoc-cluster-aws.adoc     |  4 +-
 .../byoc/azure/create-byoc-cluster-azure.adoc |  2 +-
 .../byoc/gcp/create-byoc-cluster-gcp.adoc     |  2 +-
 .../cluster-types/byoc/size-byoc-cluster.adoc | 76 +++++++++++++++++
 .../get-started/pages/whats-new-cloud.adoc    | 17 ++++
 .../cluster-maintenance/scale-cluster.adoc    | 82 +++++++++++++++++++
 modules/manage/pages/maintenance.adoc         | 21 ++++-
 modules/manage/pages/terraform-provider.adoc  | 10 ++-
 modules/reference/partials/tiers.adoc         | 16 +++-
 10 files changed, 224 insertions(+), 8 deletions(-)
 create mode 100644 modules/get-started/pages/cluster-types/byoc/size-byoc-cluster.adoc
 create mode 100644 modules/manage/pages/cluster-maintenance/scale-cluster.adoc

diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc
index 78d6a9346..df4f06d50 100644
--- a/modules/ROOT/nav.adoc
+++ b/modules/ROOT/nav.adoc
@@ -9,6 +9,7 @@
 * xref:get-started:cluster-types/index.adoc[Deploy]
 ** xref:get-started:cluster-types/serverless.adoc[Serverless]
 ** xref:get-started:cluster-types/byoc/index.adoc[BYOC]
+*** xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[]
 *** xref:get-started:cluster-types/byoc/aws/index.adoc[AWS]
 **** xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[]
 **** xref:get-started:cluster-types/byoc/aws/vpc-byo-aws.adoc[]
@@ -416,6 +417,7 @@
 ** xref:manage:cluster-maintenance/index.adoc[Cluster Maintenance]
 *** xref:manage:cluster-maintenance/cluster-state.adoc[]
 *** xref:manage:maintenance.adoc[]
+*** xref:manage:cluster-maintenance/scale-cluster.adoc[]
 *** xref:manage:cluster-maintenance/config-cluster.adoc[]
 *** xref:manage:audit-logging.adoc[]
 **** xref:manage:audit-logging/audit-log-samples.adoc[]
diff --git a/modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc b/modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc
index adf9ab19e..605370917 100644
--- a/modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc
+++ b/modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc
@@ -4,7 +4,7 @@
 
 To create a Redpanda cluster in your virtual private cloud (VPC), follow the instructions in the Redpanda Cloud UI. The UI contains the parameters necessary to successfully run `rpk cloud byoc apply`. See also: xref:get-started:byoc-arch.adoc[BYOC architecture].
 
-NOTE: With standard BYOC clusters, Redpanda manages security policies and resources for your VPC, including subnetworks, service accounts, IAM roles, firewall rules, and storage buckets. For the highest level of security, you can manage these resources yourself with a xref:./vpc-byo-aws.adoc[BYOVPC cluster on AWS].
+NOTE: With standard BYOC clusters, Redpanda manages security policies and resources for your VPC, including subnetworks, service accounts, IAM roles, firewall rules, and storage buckets. For the highest level of security, you can manage these resources yourself with a xref:get-started:cluster-types/byoc/aws/vpc-byo-aws.adoc[BYOVPC cluster on AWS].
 
 == Prerequisites
 
@@ -26,7 +26,7 @@ To verify access, you should be able to successfully run `aws sts get-caller-ide
 
 . Log in to https://cloud.redpanda.com[Redpanda Cloud^].
 . On the Clusters page, click *Create cluster*, then click *Create* for BYOC. 
-. Enter a cluster name, then select the resource group, provider (AWS), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version.
+. Enter a cluster name, then select the resource group, provider (AWS), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version. If your organization uses usage-based billing, you can describe your workload to get recommended configurations and price estimates instead of selecting a tier directly. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
 +
 [NOTE]
 ==== 
diff --git a/modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc b/modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc
index d229b5055..e33bca7c0 100644
--- a/modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc
+++ b/modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc
@@ -150,7 +150,7 @@ To create a Redpanda cluster in your Azure VNet, follow the <<prerequisites,prer
 
 . Log in to https://cloud.redpanda.com[Redpanda Cloud^].
 . On the Clusters page, click *Create cluster*, then click *Create* for BYOC.
-. Enter a cluster name, then select the resource group, provider (Azure), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version. 
+. Enter a cluster name, then select the resource group, provider (Azure), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version. If your organization uses usage-based billing, you can describe your workload to get recommended configurations and price estimates instead of selecting a tier directly. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
 +
 [NOTE]
 ==== 
diff --git a/modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc b/modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
index a2898f8a5..0450f69f2 100644
--- a/modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
+++ b/modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
@@ -29,7 +29,7 @@ include::partial$gpq-quotas.adoc[]
 . Log in to https://cloud.redpanda.com[Redpanda Cloud^].
 . On the Clusters page, click *Create cluster*, then click *Create* for BYOC.
 +
-Enter a cluster name, then select the resource group, provider (GCP), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version.
+Enter a cluster name, then select the resource group, provider (GCP), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version. If your organization uses usage-based billing, you can describe your workload to get recommended configurations and price estimates instead of selecting a tier directly. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
 +
 [NOTE]
 ====
diff --git a/modules/get-started/pages/cluster-types/byoc/size-byoc-cluster.adoc b/modules/get-started/pages/cluster-types/byoc/size-byoc-cluster.adoc
new file mode 100644
index 000000000..121c99ac3
--- /dev/null
+++ b/modules/get-started/pages/cluster-types/byoc/size-byoc-cluster.adoc
@@ -0,0 +1,76 @@
+= Size and Price a BYOC Cluster
+:description: Get machine configurations and price estimates matched to your workload before you create a BYOC cluster.
+:page-topic-type: how-to
+:personas: platform_admin
+:learning-objective-1: Describe your workload to get recommended machine configurations with price estimates
+:learning-objective-2: Compare sizing options by RPU rate, machine type, and node count
+:learning-objective-3: Request sizing estimates programmatically with the Control Plane API
+
+When you create a BYOC cluster, you can size it from your workload requirements instead of translating them into Redpanda tier terminology. Describe your workload, such as throughput, glossterm:partition[,partitions], and retention, and Redpanda recommends machine configurations with itemized price estimates.
+
+After reading this page, you will be able to:
+
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
+
+[NOTE]
+====
+Sizing options appear only for organizations on usage-based billing. If you don't see them when you create a BYOC cluster, contact your Redpanda account team.
+====
+// TODO(pm): DOC-1861 - confirm rollout state of the `enableSizingCalculator` feature flag with Julin/Denis: is it enabled for all usage-based-billing orgs in production? Also confirm what annual-commit (non-UBB) customers see, and adjust the note above.
+
+== How sizing works
+
+You can size a cluster in two ways:
+
+* *Describe your workload.* Provide workload parameters, such as partition count, ingress and egress throughput, retention, average message size, replication factor, producer count, and target latency. You can also indicate whether you plan to use cloud topics or Iceberg topics. Redpanda resolves the compute capacity your workload needs and recommends machine configurations that provide it.
+* *Specify capacity directly.* Provide a rate of Redpanda Processing Units (RPUs), from 1 to 384. One RPU represents two vCPUs of glossterm:broker[] compute. Redpanda resolves the machine configurations that deliver that capacity.
+
+Both ways return a ranked list of viable machine configurations. Each option includes the machine type, node count, RPU rate, and the xref:reference:tiers/byoc-tiers.adoc[usage tier] it maps to, along with an itemized price estimate covering compute, ingress, egress, storage, and Iceberg, with hourly and monthly totals.
+
+Price estimates use your organization's rate card.
+
+// TODO(eng): DOC-1861 - confirm how to describe estimates vs billed amounts (estimates are based on the org rate card, but actual billing depends on measured usage).
+
+== Size a cluster in the Cloud UI
+
+. Log in to https://cloud.redpanda.com[Redpanda Cloud^].
+. On the Clusters page, click *Create cluster*, then click *Create* for BYOC.
+. In the cluster settings step, describe your workload or enter an RPU rate, then compare the recommended configurations and price estimates.
+. Select a configuration and continue with the create flow for your cloud provider. See xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[AWS], xref:get-started:cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc[GCP], or xref:get-started:cluster-types/byoc/azure/create-byoc-cluster-azure.adoc[Azure].
+
+// TODO(ux): DOC-1861 - verify the exact field names and step order against the production create flow before publishing, and capture screenshots if the docs team wants them.
+
+== Size a cluster with the Control Plane API
+
+To script sizing estimates, send a `POST` request to the `/v1beta2/sizing` endpoint of the link:/api/doc/cloud-controlplane[Control Plane API^]. Include your cloud provider, region, availability zone configuration, cluster type, and either a workload description or an RPU rate. The request requires the `read:organization-info` permission.
+
+// TODO(api): DOC-1861 - verify that /v1beta2/sizing appears in the published Control Plane API reference, and replace this example with the exact request and response field names from the published OpenAPI spec. The field names below are drafted from sizing.proto and are unverified.
+
+[source,bash]
+----
+curl -X POST "https://api.redpanda.com/v1beta2/sizing" \
+  -H "Authorization: Bearer $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "cloud_provider": "CLOUD_PROVIDER_AWS",
+    "region": "us-east-1",
+    "cluster_type": "TYPE_BYOC",
+    "workload": {
+      "partition_count": 5000,
+      "ingress_mbps": 100,
+      "egress_mbps": 200,
+      "retention_days": 7,
+      "average_message_size_bytes": 1024,
+      "replication_factor": 3
+    }
+  }'
+----
+
+The response contains the resolved RPU rate and a ranked list of machine configurations, each with an itemized price breakdown.
+
+== Next steps
+
+* xref:get-started:cluster-types/byoc/index.adoc[Create a BYOC cluster]
+* xref:reference:tiers/byoc-tiers.adoc[BYOC tiers and regions]
diff --git a/modules/get-started/pages/whats-new-cloud.adoc b/modules/get-started/pages/whats-new-cloud.adoc
index c3070da3e..9d5daaac4 100644
--- a/modules/get-started/pages/whats-new-cloud.adoc
+++ b/modules/get-started/pages/whats-new-cloud.adoc
@@ -6,6 +6,23 @@
 
 This page lists new features added to Redpanda Cloud.
 
+// TODO(DOC-1861): Uncomment and file under the correct month once the sizing
+// calculator rollout is confirmed (enableSizingCalculator flag broadly enabled
+// for usage-based-billing orgs; confirm with Julin/Denis).
+////
+=== Workload-based sizing and pricing for BYOC clusters
+
+If your organization uses usage-based billing, you can now describe your workload, such as throughput, partitions, and retention, when you create a BYOC cluster, and get recommended machine configurations with itemized price estimates instead of selecting a tier directly. You can also request sizing estimates through the Control Plane API. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and Price a BYOC Cluster].
+////
+
+// TODO(DOC-1860): Replace the placeholder month heading with the actual GA month
+// before merging, and verify horizontal timing/limits and the API surface.
+== Month TBD (user scaling GA)
+
+=== Self-service cluster scaling for BYOC
+
+You can now scale a BYOC cluster up or down directly from the Redpanda Cloud UI or the Control Plane API, without contacting Redpanda Support. Add or remove brokers in about 15 to 30 minutes to absorb short-term traffic changes, or change the cluster's machine type to right-size for sustained throughput changes. See xref:manage:cluster-maintenance/scale-cluster.adoc[Scale a BYOC Cluster].
+
 == July 2026
 
 === Improved Serverless trial onboarding
diff --git a/modules/manage/pages/cluster-maintenance/scale-cluster.adoc b/modules/manage/pages/cluster-maintenance/scale-cluster.adoc
new file mode 100644
index 000000000..a3f9fdd51
--- /dev/null
+++ b/modules/manage/pages/cluster-maintenance/scale-cluster.adoc
@@ -0,0 +1,82 @@
+= Scale a BYOC Cluster
+:description: Scale a BYOC cluster up or down by changing its node count or machine type to match your workload.
+:page-topic-type: how-to
+:personas: platform_admin
+:learning-objective-1: Choose between horizontal and vertical scaling for a workload change
+:learning-objective-2: Scale a cluster up or down from the Redpanda Cloud UI
+:learning-objective-3: Explain what happens to your cluster and clients during a scaling operation
+
+// Draft for User Scaling GA (ENG-928, in development). The PR stays in
+// draft until GA ships; merge with the GA release. Before merge, resolve
+// the TODO(eng)/TODO(ux)/TODO(api) items against the shipped UI and
+// public API. Sources: ENG-928 epic, ENG-315 (LA epic). The API section
+// supports DOC-1133 (owned by Kat Batuigas - coordinate before editing).
+// Simon Lord's "User Scaling - beta internal notes" Confluence page is
+// restricted; request access to firm up the UI flow before GA.
+
+Scale a BYOC cluster up or down as your workload changes, without contacting Redpanda Support. You can add or remove glossterm:broker[,brokers] to absorb short-term changes in traffic, or change the machine type to right-size the cluster for a sustained change in throughput.
+
+After reading this page, you will be able to:
+
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
+
+== Choose a scaling method
+
+You can scale a cluster in two ways:
+
+[cols="1,2,2", options="header"]
+|===
+| Method | What changes | When to use it
+
+| Horizontal scaling
+| Adds or removes brokers of the current machine type. Completes in about 15 to 30 minutes.
+| Intraday changes in traffic, such as daily peaks or batch windows.
+
+| Vertical scaling
+| Changes the machine type that the cluster runs on. Redpanda decommissions the existing brokers and recommissions brokers of the new type, which takes a few hours.
+| Sustained changes in throughput on a timescale of days, such as scaling up for weekdays and down for weekends.
+|===
+
+// TODO(eng): DOC-1860 - confirm at GA (Simon Lord): (1) is the 24-node horizontal maximum a GA limit or a tested-so-far number, (2) availability and client impact during vertical scaling (partition movement, latency), (3) confirm scale-to-zero is out of scope (Aha comment flagged confusion between "user scaling" and "scale to zero").
+
+If you are not sure how much capacity your workload needs, describe your workload in the sizing calculator to get recommended configurations and price estimates. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
+
+== Scale a cluster in the Cloud UI
+
+// TODO(ux): DOC-1860 - replace with the shipped UI flow at GA. The steps below are a placeholder drafted from the ENG-928 design intent (scaling UX integrates the sizing calculator so you scale in workload terms).
+
+. Log in to https://cloud.redpanda.com[Redpanda Cloud^] and open your cluster.
+. Open the cluster's settings and select the option to resize the cluster.
+. Describe your new workload requirements, or select a target configuration (machine type and broker count).
+. Review the price estimate for the new configuration, then confirm.
+. Monitor the scaling operation's progress from the cluster overview.
+
+== Scale a cluster with the Control Plane API
+
+// TODO(api): DOC-1133 (Kat Batuigas) - document the public API surface when it ships with GA. As of 2026-07-15, the public cluster.proto (v1beta2) has no scaling fields; ScaleCluster exists only in the internal admin API. Confirm whether GA ships a new scaling endpoint or new UpdateCluster fields, and add request/response examples from the published OpenAPI spec.
+
+== What happens during scaling
+
+// TODO(eng): DOC-1860 - verify this section with engineering at GA.
+
+During both horizontal and vertical scaling, your cluster continues to serve traffic and its endpoints do not change:
+
+* When scaling horizontally, Redpanda adds or removes brokers and rebalances glossterm:partition[] data and leadership across the resulting set of brokers.
+* When scaling vertically, Redpanda provisions brokers of the new machine type, moves partition data and leadership to them in a rolling fashion, then decommissions the original brokers.
+
+When Redpanda decommissions a broker, the broker's client connections restart, and all mainstream Kafka client libraries reconnect automatically.
+
+== Limits
+
+* You can scale horizontally up to 24 brokers.
+* Scaling applies to BYOC clusters only.
+
+// TODO(eng): DOC-1860 - confirm both limits at GA. (Per docs plan 2026-07-20, we assume scaling is not feature-gated at GA and is available to all BYOC clusters.)
+
+== Next steps
+
+* xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster]
+* xref:manage:maintenance.adoc#tier-migrations[Tier migrations]
+* xref:manage:monitor-cloud.adoc[Monitor your cluster]
diff --git a/modules/manage/pages/maintenance.adoc b/modules/manage/pages/maintenance.adoc
index 9ecffc2a6..8483d66b4 100644
--- a/modules/manage/pages/maintenance.adoc
+++ b/modules/manage/pages/maintenance.adoc
@@ -3,7 +3,7 @@
 :page-topic-type: concepts
 :personas: platform_admin, app_developer, streaming_developer
 :learning-objective-1: Compare minor upgrades, major upgrades, and deprecations and what to expect from each
-:learning-objective-2: Explain how scheduled maintenance windows work for BYOC and Dedicated clusters
+:learning-objective-2: Explain how scheduled maintenance windows and tier migrations work for BYOC and Dedicated clusters
 :learning-objective-3: Distinguish maintenance behavior for Serverless versus BYOC and Dedicated clusters
 
 As a fully-managed service, the Redpanda Cloud glossterm:control plane[] handles all maintenance operations, such as upgrades to your software and infrastructure. Here, _control plane_ refers to the Redpanda Cloud managed service that orchestrates cluster operations, not the Kubernetes control plane.
@@ -30,6 +30,25 @@ If you select a *Scheduled* maintenance window, then Redpanda Cloud runs operati
 
 TIP: Redpanda Cloud maintenance cycles always start on Tuesdays. Clusters scheduled for maintenance on Tuesdays are updated first, and clusters scheduled on Mondays are updated last. Keep this in mind when sequencing updates for multiple clusters.
 
+[[tier-migrations]]
+== Tier migrations
+
+You can move a BYOC or Dedicated cluster to a different xref:reference:tiers/byoc-tiers.adoc[usage tier] as your workload changes, for example to scale up before expected traffic growth, or to scale down after peak demand. To request a tier change, contact https://support.redpanda.com/hc/en-us/requests/new[Redpanda Support^]. Redpanda runs the migration for you, and your maintenance window controls when it starts.
+
+// TODO(eng): Confirm guardrails with engineering (ENG-450, Nate Cole): can customers move multiple tiers in one migration, or one tier at a time? Also confirm typical migration duration per tier step.
+
+A tier migration changes the compute resources underlying your cluster while the cluster continues to serve traffic:
+
+. Redpanda provisions new brokers that match the target tier.
+. Partition data and leadership move to the new brokers in a rolling fashion, accompanied by health checks.
+. Redpanda decommissions and removes the original brokers.
+
+Your cluster's endpoints do not change. When Redpanda decommissions a broker, the broker's client connections restart, and all mainstream Kafka client libraries reconnect automatically.
+
+Like other maintenance operations, tier migrations begin during your scheduled maintenance window, but a migration may complete after the window closes.
+
+NOTE: If you manage your cluster with the Redpanda Terraform provider, add a `lifecycle` block that ignores changes to `throughput_tier` before requesting a tier migration. Otherwise, the next `terraform apply` destroys and replaces the cluster. See xref:manage:terraform-provider.adoc#limitations[Redpanda Terraform provider limitations].
+
 [[serverless-maintenance]]
 == Serverless maintenance
 
diff --git a/modules/manage/pages/terraform-provider.adoc b/modules/manage/pages/terraform-provider.adoc
index d97800914..51537a6ed 100644
--- a/modules/manage/pages/terraform-provider.adoc
+++ b/modules/manage/pages/terraform-provider.adoc
@@ -132,9 +132,17 @@ lifecycle {
 }
 ----
 +
-This setting protects your cluster in the event Redpanda Support upgrades your cluster's throughput tier. Without it, the next `terraform apply` command triggers replacement.
+This setting protects your cluster when Redpanda migrates it to a different tier, for example after you request a xref:manage:maintenance.adoc#tier-migrations[tier migration]. Without it, the next `terraform apply` command triggers replacement.
 ====
 
+// TODO(DOC-1860, gated on ENG-928): When user scaling reaches GA, revise the
+// warning above. Self-service scaling replaces the support-mediated tier-change
+// framing, and the provider story needs eng confirmation: does the provider gain
+// scaling support (machine type and node count fields, or in-place
+// throughput_tier updates), or should customers scale through the UI/API and
+// keep the ignore_changes lifecycle block? Coordinate with DOC-1133 (Kat
+// Batuigas) for the API surface.
+
 == Prerequisites
 
 [IMPORTANT]
diff --git a/modules/reference/partials/tiers.adoc b/modules/reference/partials/tiers.adoc
index aa229dc71..24d759276 100644
--- a/modules/reference/partials/tiers.adoc
+++ b/modules/reference/partials/tiers.adoc
@@ -1,7 +1,11 @@
 ifdef::env-byoc[]
 == BYOC usage tiers
 
-When you create a BYOC cluster, you select your usage tier. Each tier provides tested workload configurations for maximum throughput, partitions, and connections. 
+When you create a BYOC cluster, you select your usage tier. Each tier defines a tested workload configuration with maximum (up to) values for throughput, partitions, and connections.
+
+Treat tier values as guidance rather than enforced caps. Redpanda does not throttle your workload at the advertised values. You can push one dimension beyond its advertised value, for example ingress throughput, by accepting trade-offs in other dimensions, such as egress capacity or latency.
+
+// TODO(eng): DOC-940 (Travis Downs sync) - confirm before publishing: (1) no dimension is throttled or otherwise enforced, (2) approved wording for exceeding advertised values, (3) tier table values are current. Tristan Stevens' June 2025 hold on DOC-940 must be confirmed lifted.
 
 |=== 
 | Tier | Ingress | Egress | Partitions (pre-replication) | Connections
@@ -23,10 +27,18 @@ When you create a BYOC cluster, you select your usage tier. Each tier provides t
 * On Azure, tiers 1-5 are supported.
 * Redpanda supports compute-optimized tiers with AWS Graviton3 processors.
 * Depending on the workload, it may not be possible to achieve all maximum values. For example, a high number of partitions may make it more difficult to reach the maximum value in throughput.
-* Connections are regulated per broker for best performance. For example, in a tier 1 cluster with 3 brokers, there could be up to 3,000 connections per broker. 
+* Connections are regulated per broker for best performance. For example, in a tier 1 cluster with 3 brokers, there could be up to 3,000 connections per broker.
 
 ====
 
+=== Machine types and RPUs
+
+Each tier maps to a machine type from your cloud provider, sized in Redpanda Processing Units (RPUs). One RPU represents two vCPUs of broker compute. Redpanda uses RPUs for cluster sizing and usage-based pricing.
+
+To see the machine type and RPU count for each tier, use the link:/api/doc/cloud-controlplane[Control Plane API^] (`GET /v1beta2/throughput-tiers`). To get a machine configuration and price estimate matched to your workload instead of choosing a tier directly, see xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
+
+// TODO(eng): DOC-940/DOC-1861 - verify the public tiers endpoint path in the published Control Plane API reference (GET /v1beta2/throughput-tiers vs /v1beta2/tiers) before publishing.
+
 == BYOC supported regions
 
 [tabs]

From 3a087543d851c86311891a2724f6f91a2c1057b1 Mon Sep 17 00:00:00 2001
From: micheleRP <michele@redpanda.com>
Date: Mon, 20 Jul 2026 18:30:57 -0600
Subject: [PATCH 2/2] Incorporate PM messaging: calculator-first sizing,
 de-emphasize RPUs

Per Denis Coady (Cloud PM, Slack 2026-07-20): customers should size and
resize clusters with the workload calculator rather than reasoning in
tiers or RPUs.

- tiers partial: lead with workload-based sizing for usage-based-billing
  orgs; reframe RPU as an internal unit resolved by the calculator;
  TODO(pm) on whether docs may state the tier phase-out
- size-byoc-cluster: state workload-based sizing as the recommended
  path; scope manual RPU mode to users who already know their capacity
- scale-cluster: TODO(eng) for the upcoming single load metric as the
  when-to-scale signal (cross-ref DOC-1381)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../pages/cluster-types/byoc/size-byoc-cluster.adoc       | 4 ++--
 .../manage/pages/cluster-maintenance/scale-cluster.adoc   | 2 ++
 modules/reference/partials/tiers.adoc                     | 8 +++++---
 3 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/modules/get-started/pages/cluster-types/byoc/size-byoc-cluster.adoc b/modules/get-started/pages/cluster-types/byoc/size-byoc-cluster.adoc
index 121c99ac3..72eea71bb 100644
--- a/modules/get-started/pages/cluster-types/byoc/size-byoc-cluster.adoc
+++ b/modules/get-started/pages/cluster-types/byoc/size-byoc-cluster.adoc
@@ -6,7 +6,7 @@
 :learning-objective-2: Compare sizing options by RPU rate, machine type, and node count
 :learning-objective-3: Request sizing estimates programmatically with the Control Plane API
 
-When you create a BYOC cluster, you can size it from your workload requirements instead of translating them into Redpanda tier terminology. Describe your workload, such as throughput, glossterm:partition[,partitions], and retention, and Redpanda recommends machine configurations with itemized price estimates.
+When you create a BYOC cluster, size it from your workload requirements instead of translating them into Redpanda tier terminology. Describe your workload, such as throughput, glossterm:partition[,partitions], and retention, and Redpanda recommends machine configurations with itemized price estimates. Workload-based sizing is the recommended way to size a cluster: it applies the same logic Redpanda's performance team uses, and it stays accurate as performance improvements change what a given configuration can handle.
 
 After reading this page, you will be able to:
 
@@ -25,7 +25,7 @@ Sizing options appear only for organizations on usage-based billing. If you don'
 You can size a cluster in two ways:
 
 * *Describe your workload.* Provide workload parameters, such as partition count, ingress and egress throughput, retention, average message size, replication factor, producer count, and target latency. You can also indicate whether you plan to use cloud topics or Iceberg topics. Redpanda resolves the compute capacity your workload needs and recommends machine configurations that provide it.
-* *Specify capacity directly.* Provide a rate of Redpanda Processing Units (RPUs), from 1 to 384. One RPU represents two vCPUs of glossterm:broker[] compute. Redpanda resolves the machine configurations that deliver that capacity.
+* *Specify capacity directly.* Provide a rate of Redpanda Processing Units (RPUs), from 1 to 384. One RPU represents two vCPUs of glossterm:broker[] compute. Redpanda resolves the machine configurations that deliver that capacity. Use this mode only if you already know the capacity you need; describing your workload is the recommended path.
 
 Both ways return a ranked list of viable machine configurations. Each option includes the machine type, node count, RPU rate, and the xref:reference:tiers/byoc-tiers.adoc[usage tier] it maps to, along with an itemized price estimate covering compute, ingress, egress, storage, and Iceberg, with hourly and monthly totals.
 
diff --git a/modules/manage/pages/cluster-maintenance/scale-cluster.adoc b/modules/manage/pages/cluster-maintenance/scale-cluster.adoc
index a3f9fdd51..ec335229b 100644
--- a/modules/manage/pages/cluster-maintenance/scale-cluster.adoc
+++ b/modules/manage/pages/cluster-maintenance/scale-cluster.adoc
@@ -43,6 +43,8 @@ You can scale a cluster in two ways:
 
 If you are not sure how much capacity your workload needs, describe your workload in the sizing calculator to get recommended configurations and price estimates. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
 
+// TODO(eng): DOC-1860 - Core is releasing a single load metric for judging whether a cluster is over- or under-provisioned, and PM wants it exposed to users (Denis Coady, Slack 2026-07-20; Piyush Agarwal owns exposure timing; may not be RPU-aware, check Tyson/Matt). When it ships, document it here as the signal for deciding when to scale. Related: DOC-1381 tracks the Self-Managed load factor dashboard.
+
 == Scale a cluster in the Cloud UI
 
 // TODO(ux): DOC-1860 - replace with the shipped UI flow at GA. The steps below are a placeholder drafted from the ENG-928 design intent (scaling UX integrates the sizing calculator so you scale in workload terms).
diff --git a/modules/reference/partials/tiers.adoc b/modules/reference/partials/tiers.adoc
index 24d759276..d679f10ae 100644
--- a/modules/reference/partials/tiers.adoc
+++ b/modules/reference/partials/tiers.adoc
@@ -1,7 +1,9 @@
 ifdef::env-byoc[]
 == BYOC usage tiers
 
-When you create a BYOC cluster, you select your usage tier. Each tier defines a tested workload configuration with maximum (up to) values for throughput, partitions, and connections.
+When you create a BYOC cluster, you choose its capacity. If your organization uses usage-based billing, describe your workload and let Redpanda recommend a configuration, rather than choosing a tier directly. See xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and Price a BYOC Cluster]. Otherwise, you select a usage tier. Each tier defines a tested workload configuration with maximum (up to) values for throughput, partitions, and connections.
+
+// TODO(pm): DOC-940/DOC-1861 - Denis Coady (Slack, 2026-07-20) says tiers are being phased out in favor of calculator-based sizing and customers shouldn't reason in tiers or RPUs. Asked on PR #642 whether docs should state a phase-out or keep "recommended" framing. Do not state a phase-out without official deprecation comms.
 
 Treat tier values as guidance rather than enforced caps. Redpanda does not throttle your workload at the advertised values. You can push one dimension beyond its advertised value, for example ingress throughput, by accepting trade-offs in other dimensions, such as egress capacity or latency.
 
@@ -33,9 +35,9 @@ Treat tier values as guidance rather than enforced caps. Redpanda does not throt
 
 === Machine types and RPUs
 
-Each tier maps to a machine type from your cloud provider, sized in Redpanda Processing Units (RPUs). One RPU represents two vCPUs of broker compute. Redpanda uses RPUs for cluster sizing and usage-based pricing.
+Each tier maps to a machine type from your cloud provider, with capacity measured in Redpanda Processing Units (RPUs), the internal unit that workload-based sizing and usage-based pricing use. You don't need to reason in RPUs: describe your workload in the xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[sizing calculator], and Redpanda resolves the machine configuration for you.
 
-To see the machine type and RPU count for each tier, use the link:/api/doc/cloud-controlplane[Control Plane API^] (`GET /v1beta2/throughput-tiers`). To get a machine configuration and price estimate matched to your workload instead of choosing a tier directly, see xref:get-started:cluster-types/byoc/size-byoc-cluster.adoc[Size and price a BYOC cluster].
+To see the machine type and RPU count for each tier, use the link:/api/doc/cloud-controlplane[Control Plane API^] (`GET /v1beta2/throughput-tiers`).
 
 // TODO(eng): DOC-940/DOC-1861 - verify the public tiers endpoint path in the published Control Plane API reference (GET /v1beta2/throughput-tiers vs /v1beta2/tiers) before publishing.