diff --git a/website/docs/components/terraform/workspaces.mdx b/website/docs/components/terraform/workspaces.mdx
index a3450694ec..53aaa9b229 100644
--- a/website/docs/components/terraform/workspaces.mdx
+++ b/website/docs/components/terraform/workspaces.mdx
@@ -193,6 +193,7 @@ refer to [Atmos Component Inheritance](/howto/inheritance)
## References
+- [Component Metadata](/stacks/components/component-metadata) - Configure `terraform_workspace` and `terraform_workspace_pattern`
- [Terraform Workspaces](https://developer.hashicorp.com/terraform/language/state/workspaces)
- [Managing Terraform Workspaces](https://developer.hashicorp.com/terraform/cli/workspaces)
- [Terraform Environment Variables](https://developer.hashicorp.com/terraform/cli/config/environment-variables)
diff --git a/website/docs/howto/inheritance.mdx b/website/docs/howto/inheritance.mdx
index 3a3e0ad1d7..936770dffe 100644
--- a/website/docs/howto/inheritance.mdx
+++ b/website/docs/howto/inheritance.mdx
@@ -22,7 +22,7 @@ Atmos supports the following concepts and principles of **Component-Oriented Pro
component
These concepts and principles are implemented and used in Atmos by combining two features: [`import`](/stacks/imports)
-and [`metadata`](/stacks/metadata) component's configuration section.
+and [`metadata`](/stacks/components/component-metadata) component's configuration section.
:::info
The mechanics of mixins and inheritance apply only to the [Stack](/learn/stacks) configurations. Atmos knows nothing about the underlying
diff --git a/website/docs/stacks/components/helmfile.mdx b/website/docs/stacks/components/helmfile.mdx
index bf2555fe7b..6b06d8d12d 100644
--- a/website/docs/stacks/components/helmfile.mdx
+++ b/website/docs/stacks/components/helmfile.mdx
@@ -27,7 +27,7 @@ Helmfile components support the common configuration sections:
[`settings`](/stacks/settings)
Integrations and metadata.
- [`metadata`](/stacks/metadata)
+ [`metadata`](/stacks/components/component-metadata)
Component behavior and inheritance.
[`command`](/stacks/command)
diff --git a/website/docs/stacks/components/index.mdx b/website/docs/stacks/components/index.mdx
index e53651d8bc..36e4ab4602 100644
--- a/website/docs/stacks/components/index.mdx
+++ b/website/docs/stacks/components/index.mdx
@@ -47,7 +47,7 @@ All component types support these configuration sections:
[`settings`](/stacks/settings)
Integrations and custom metadata.
- [`metadata`](/stacks/metadata)
+ [`metadata`](/stacks/components/component-metadata)
Component behavior and inheritance. See [Metadata Attributes](#metadata-attributes) below.
[`command`](/stacks/command)
diff --git a/website/docs/stacks/metadata.mdx b/website/docs/stacks/components/metadata.mdx
similarity index 76%
rename from website/docs/stacks/metadata.mdx
rename to website/docs/stacks/components/metadata.mdx
index d7a855e16e..bd56d85f55 100644
--- a/website/docs/stacks/metadata.mdx
+++ b/website/docs/stacks/components/metadata.mdx
@@ -1,10 +1,10 @@
---
title: Configure Component Metadata
-sidebar_position: 13
-sidebar_label: metadata
+sidebar_position: 5
+sidebar_label: "*.metadata"
sidebar_class_name: command
description: Use the metadata section to control component behavior, inheritance, and deployment settings.
-id: metadata
+id: component-metadata
---
import File from '@site/src/components/File'
import Intro from '@site/src/components/Intro'
@@ -135,6 +135,70 @@ When `locked: true`:
- Atmos will warn or prevent changes to the component
- Useful for protecting critical infrastructure components
+### `terraform_workspace`
+
+Overrides the Terraform workspace name with a literal string value:
+
+```yaml
+components:
+ terraform:
+ vpc:
+ metadata:
+ terraform_workspace: "custom-workspace-name"
+```
+
+By default, Atmos calculates workspace names automatically based on the stack name. Use this field when you need explicit control over the workspace name.
+
+For detailed information about how Atmos manages Terraform workspaces, see [Workspaces](/components/terraform/workspaces).
+
+### `terraform_workspace_pattern`
+
+Overrides the Terraform workspace name using a pattern with context tokens:
+
+```yaml
+components:
+ terraform:
+ vpc:
+ metadata:
+ terraform_workspace_pattern: "{tenant}-{environment}-{stage}"
+```
+
+Supported tokens:
+- `{namespace}` - The namespace from context variables
+- `{tenant}` - The tenant from context variables
+- `{environment}` - The environment from context variables
+- `{region}` - The region from context variables
+- `{stage}` - The stage from context variables
+- `{attributes}` - The attributes from context variables
+- `{component}` - The Atmos component name
+- `{base-component}` - The base component name (from `metadata.component`)
+
+For detailed information about workspace patterns and examples, see [Workspaces](/components/terraform/workspaces).
+
+### `custom`
+
+A user extension point for storing arbitrary metadata that Atmos preserves but does not interpret:
+
+```yaml
+components:
+ terraform:
+ vpc:
+ metadata:
+ custom:
+ owner: platform-team
+ cost_center: "12345"
+ tier: critical
+```
+
+Use `custom` for:
+- Storing metadata for external tooling to consume (CI/CD pipelines, dashboards)
+- Adding labels or annotations readable via `atmos describe stacks`
+- Custom categorization that doesn't affect Atmos behavior
+
+:::note
+Unlike `vars` and `settings`, the `custom` section is **not inherited** by derived components. Each component must define its own `custom` values.
+:::
+
## Examples
### Multiple Instances from One Module
diff --git a/website/docs/stacks/components/packer.mdx b/website/docs/stacks/components/packer.mdx
index 68af6a0fc3..dd17471670 100644
--- a/website/docs/stacks/components/packer.mdx
+++ b/website/docs/stacks/components/packer.mdx
@@ -27,7 +27,7 @@ Packer components support the common configuration sections:
[`settings`](/stacks/settings)
Integrations and metadata.
- [`metadata`](/stacks/metadata)
+ [`metadata`](/stacks/components/component-metadata)
Component behavior and inheritance.
[`command`](/stacks/command)
diff --git a/website/docs/stacks/components/terraform.mdx b/website/docs/stacks/components/terraform.mdx
index fa0875ceb3..9932c76dda 100644
--- a/website/docs/stacks/components/terraform.mdx
+++ b/website/docs/stacks/components/terraform.mdx
@@ -27,7 +27,7 @@ Terraform components support all common sections plus Terraform-specific options
[`settings`](/stacks/settings)
Integrations and metadata.
- [`metadata`](/stacks/metadata)
+ [`metadata`](/stacks/components/component-metadata)
Component behavior and inheritance.
[`command`](/stacks/command)
diff --git a/website/docs/stacks/stacks.mdx b/website/docs/stacks/stacks.mdx
index 5e06d50646..11afff981f 100644
--- a/website/docs/stacks/stacks.mdx
+++ b/website/docs/stacks/stacks.mdx
@@ -23,7 +23,7 @@ Stack manifests support various configuration sections at different scopes:
| [vars](/stacks/vars) | Variables passed to components | Global, component-type, component |
| [env](/stacks/env) | Environment variables | Global, component-type, component |
| [settings](/stacks/settings) | Integrations and metadata | Global, component-type, component |
-| [metadata](/stacks/metadata) | Component behavior and inheritance | Component only |
+| [metadata](/stacks/components/component-metadata) | Component behavior and inheritance | Component only |
| [hooks](/stacks/hooks) | Lifecycle event handlers | Global, component-type, component |
| [command](/stacks/command) | Override default executable | Component-type, component |
| [backend](/stacks/backend) | Terraform state storage | Component-type, component |