diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c596192..058eaa0f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,8 @@
+# v0.23.1
+
+DEPRECATIONS:
+- `meshstack_tenant`: deprecated in favor of `meshstack_tenant_v4`. Only `meshstack_tenant_v4` exposes the tenant `uuid` (and a `ref`) required to target tenants from the `meshstack_building_block` resource. Using `meshstack_tenant` now emits a deprecation warning. There is no automatic state migration between the two resource types; move existing tenants over by importing them into `meshstack_tenant_v4`.
+
 # v0.23.0
 
 FEATURES:
diff --git a/internal/provider/tenant_resource.go b/internal/provider/tenant_resource.go
index 2df17e26..1b07b75c 100644
--- a/internal/provider/tenant_resource.go
+++ b/internal/provider/tenant_resource.go
@@ -43,6 +43,7 @@ func (r *tenantResource) Configure(_ context.Context, req resource.ConfigureRequ
 func (r *tenantResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "Single tenant by workspace, project, and platform.",
+		DeprecationMessage:  "Use `meshstack_tenant_v4` instead, which exposes the tenant `uuid` (and a `ref`) required to target tenants from `meshstack_building_block`. There is no automatic state migration between the two resource types; move existing tenants over by importing them into `meshstack_tenant_v4`.",
 
 		Attributes: map[string]schema.Attribute{
 			"metadata": schema.SingleNestedAttribute{