Repo sync

content/terraform-docs-common/docs/cloud-docs/migrate/index.mdx

@@ -90,3 +90,16 @@ Refer to the following external article for an example of how to create a script
 > **Hands-on:** Complete the [Migrate to HCP Terraform in bulk](/terraform/tutorials/cloud/bulk-migrate-hcp) tutorial to get started with tf-migrate.
 
 You can use the `tf-migrate` CLI tool to automatically migrate state to HCP Terraform and Terraform Enterprise. The tool does not ship with HCP Terraform. You must download and install the binary for the CLI tool separately. Refer to the [`tf-migrate` documentation](/terraform/migrate) for more information.
+
+<!-- BEGIN: TFC:only name:stacks-tfe -->
+
+## Migrate a workspace to a Stack
+
+In HCP Terraform, there are two ways of organizing your infrastructure:
+
+- Workspaces are ideal for managing a self-contained infrastructure of one Terraform root module.
+- Stacks are ideal for managing multiple infrastructure modules and repeating that infrastructure at scale.
+
+If you have an existing workspace that you want to convert to a Stack, you can use the Terraform migrate CLI to migrate your workspace state and configuration to a Stack in HCP Terraform. Refer to the [Terraform migrate CLI](/terraform/migrate/stacks) to learn more.
+
+<!-- END: TFC:only name:stacks-tfe -->

content/terraform-docs-common/docs/cloud-docs/stack-workspace.mdx

@@ -28,7 +28,7 @@ Workspaces provide a hard separation between environments because each workspace
 
 If your team uses a branching strategy where each environment maps to a separate Git branch, workspaces can align with your workflow. You can promote changes across environments through pull requests between branches. Workspaces also work well when CI/CD pipelines control promotion across environments, especially when a promotion must be gated by approvals or automated test outcomes.
 
-Previously, those looking to deploy repeatable infrastructure using HCP Terraform would create separate workspaces and then use run triggers or other automation tools to coordinate changes between them. However, workspaces are not truly coupled to each other, hampering your ability to flexibly manage infrastructure as it scales. If you have a tightly orchestrated infrastructure that changes across different environments, we recommend defining a Stack.
+Previously, those looking to deploy repeatable infrastructure using HCP Terraform would create separate workspaces and then use run triggers or other automation tools to coordinate changes between them. However, workspaces are not truly coupled to each other, hampering your ability to flexibly manage infrastructure as it scales. If you have a tightly orchestrated infrastructure that changes across different environments, we recommend defining a Stack. If you want to migrate an existing workspace to a Stack, refer to the [Terraform migrate CLI](/terraform/migrate/stacks).
 
 Workspaces do support validating your code with policies, drift detection, and a range of other features that Stacks do not support. Refer to [Feature support](#feature-support) to learn more.
 
@@ -45,7 +45,7 @@ We recommend using Stacks if your use case meets any of the following conditions
 - You repeat infrastructure across different environments, regions, or accounts that require consistent and synchronized deployments.
 - You have a tightly orchestrated infrastructure that changes across different environments.
 
-Stacks codify the entire behavior of your infrastructure lifecycle within version-controlled configuration files. To learn more about Stacks and review examples, refer to [Stack use cases](/terraform/language/stacks/use-cases).
+Stacks codify the entire behavior of your infrastructure lifecycle within version-controlled configuration files. To learn more about Stacks and review examples, refer to [Stack use cases](/terraform/language/stacks/use-cases). If you want to migrate an existing workspace to a Stack, refer to the [Terraform migrate CLI](/terraform/migrate/stacks).
 
 Stacks were designed to simplify and scale Terraform workflows that become complex or repetitive using workspaces. When you use a Stack, HCP Terraform automatically recognizes the dependency between components, automatically deferring the component's plan and apply steps until it can complete them successfully. Learn more about how Stacks plan [deferred changes](/terraform/cloud-docs/stacks/deploy/runs#deferred-changes).
 

content/terraform-docs-common/docs/cloud-docs/stacks/create.mdx

@@ -31,6 +31,8 @@ You can create a Stack using any of the following methods:
 - The HCP Terraform UI
 - The Terraform CLI
 
+If you want to migrate an existing workspace to a Stack, refer to the [Terraform migrate CLI](/terraform/migrate/stacks).
+
 If you are creating a Stack in an organization for the first time, you must enable Stacks for your organization. Navigate to your organization’s **Settings** page, and in the **General** settings, check the box next to **Stacks**.
 
 ### HCP Terraform workflow

content/terraform/v1.13.x/docs/language/block/stack/tfdeploy/deployment.mdx

@@ -156,7 +156,7 @@ We recommend using the `destroy` argument to remove deployments to ensure your c
 
 ### `import`
 
-The `import` argument is a placeholder for future functionality.
+The `tf-migrate` CLI can migrate the state of an existing HCP Terraform workspace to a Stack deployment. The `tf-migrate` CLI automatically sets the `import` argument to `true` when importing the state of an existing workspace to a specific deployment.
 
 ```hcl
 deployment "<LABEL>" {
@@ -168,6 +168,10 @@ deployment "<LABEL>" {
 }
 ```
 
+Terraform migrate sets the `import` argument to let HCP Terraform know that the rest of the deployments in a Stack can continue plan as normal while the deployment with `import` is migrating state.
+
+To learn more about migrating a workspace to a Stack deployment, refer to [Terraform migrate](/terraform/migrate/stacks).
+
 #### Summary
 
 - Data type: Boolean

content/terraform/v1.14.x (rc)/docs/language/block/stack/tfdeploy/deployment.mdx

@@ -155,7 +155,7 @@ We recommend using the `destroy` argument to remove deployments to ensure your c
 
 ### `import`
 
-The `import` argument is a placeholder for future functionality.
+The `tf-migrate` CLI can migrate the state of an existing HCP Terraform workspace to a Stack deployment. The `tf-migrate` CLI automatically sets the `import` argument to `true` when importing the state of an existing workspace to a specific deployment.
 
 ```hcl
 deployment "<LABEL>" {
@@ -167,6 +167,10 @@ deployment "<LABEL>" {
 }
 ```
 
+Terraform migrate sets the `import` argument to let HCP Terraform know that the rest of the deployments in a Stack can continue plan as normal while the deployment with `import` is migrating state.
+
+To learn more about migrating a workspace to a Stack deployment, refer to [Terraform migrate](/terraform/migrate/stacks).
+
 #### Summary
 
 - Data type: Boolean