Restructure namespace docs

docs/best-practices/managing-namespace.mdx

@@ -1,8 +1,8 @@
 ---
 id: managing-namespace
-title: Managing a Namespace
-sidebar_label: Managing a Namespace
-description: Best practices for managing Temporal Namespaces including configuration, retention, and optimization strategies.
+title: Namespace Best Practices
+sidebar_label: Namespace Best Practices
+description: Best practices for organizing and managing Temporal Namespaces, including naming conventions, organizational patterns, and production safeguards.
 toc_max_heading_level: 4
 keywords:
   - namespace management
@@ -14,121 +14,150 @@ tags:
   - Namespaces
 ---
 
-A [Namespace](https://docs.temporal.io/namespaces) is a unit of isolation within the Temporal platform. It ensures that workflow executions, task queues, and resources are logically separated, preventing any conflicts and enabling safe multi-tenant usage.
+:::info Applies to both open source and Temporal Cloud
+This page covers namespace best practices that apply to **both** open source Temporal and Temporal Cloud.
+Platform-specific guidance is clearly labeled throughout.
 
-Namespaces are created on the Temporal Service, and one Namespace will not impact another on the same Temporal Service. However, a single Namespace can be multi-tenant, and they act solely as a logical separation. 
+For reference documentation, see:
+- [Namespace concepts](/namespaces)
+- [Managing Namespaces (open source)](/self-hosted-guide/namespaces)
+- [Namespaces (Temporal Cloud)](/cloud/namespaces)
+:::
 
-If you are running Temporal on your own, you might be familiar with services within a cluster, such as the front-end, backend, matching service, and more. In Temporal Cloud all of these services are managed by us, so you don’t have to worry about managing them at all!
+A [Namespace](/namespaces) is a unit of isolation within the Temporal Platform.
+It ensures that Workflow Executions, Task Queues, and resources are logically separated, preventing conflicts and enabling safe multi-tenant usage.
 
-## How to Register a Namespace
+## Naming Conventions
 
-[Registering a Namespace](https://docs.temporal.io/namespaces#registration) creates the Namespace on the Temporal Service. You’re also required to set the retention period when creating the Namespace. 
+### Use lowercase and hyphens
 
-On Temporal Cloud, use the Temporal Cloud UI or `tcld` commands to create and manage Namespaces. If no other Namespace is specified, the Temporal Service uses the Namespace `default` for all Temporal SDKs and the Temporal CLI. 
+Use lowercase letters and hyphens (`-`) as separators in Namespace names.
 
-Temporal Cloud enforces limits on Namespace count and workflow execution size. You are allowed up to **10 Namespaces by default**. Exceeding this limit requires a support ticket. 
+- **Temporal Cloud**: Namespace names are case-insensitive, so `MyNamespace` and `mynamespace` refer to the same Namespace.
+- **Open source**: Namespace names are case-sensitive, so `MyNamespace` and `mynamespace` are different Namespaces.
 
-When it comes to naming Namespaces for your team, we recommend grouping them by factors such as teams, products or lines of business. You’ll also likely want to distinguish between dev and prod environments in the naming convention.
+To avoid confusion across environments, always use lowercase.
 
-Each Namespace in Temporal Cloud runs in a specific region, which determines where your workflows and data are hosted. Temporal Cloud currently runs on AWS and GCP, with support for other clouds planned for the future. 
+**Example**: `payment-checkout-prd`
 
-While your cloud infrastructure might be limited to a single region, Temporal Cloud supports multiple regions, and you’ll have access to a full list of available regions during Namespace creation. To view the current list of supported regions and their operational status, visit: https://status.temporal.io
+### Follow a consistent naming pattern
 
-### Best Practices:
+Use a pattern like `<use-case>-<domain>-<environment>` to name Namespaces:
 
-#### 1. Use lowercase and hyphens for Namespace names: Temporal Cloud treats Namespace names as case-insensitive. To maintain consistency and avoid potential issues, use lowercase letters and hyphen (-) as separators. Example: `payment-checkout-prd`
+| Component | Max Length | Examples |
+|-----------|------------|----------|
+| Use case | 10 chars | `payments`, `fulfill`, `orders` |
+| Domain | 10 chars | `checkout`, `notify`, `inventory` |
+| Environment | 3 chars | `dev`, `stg`, `prd` |
 
-#### 2. Use domain, service, and environment to name Namespaces
-Use the following pattern to name Temporal Namespaces: `<use-case>-<domain>-<region>-<environment>`
-
-  The following rules ensure that the Namespace name doesn’t exceed [39 characters](https://docs.temporal.io/cloud/namespaces#temporal-cloud-namespace-name):
-  - Use at most 10 characters for `use case` (e.g. `payments`, `fulfill`)
-  - Use at most 10 character for `domain` (e.g. `checkout`, `notify`)
-  - Use at most 5 characters for `region` (e.g. `aps1`, `apse1`)
-  - Use at most 3 characters for `environment` (e.g. `dev`, `prd`)
-
-  Examples: `payments-checkout-dev`, `payments-checkout-prd`, `fulfill-notify-prd`
+**Examples**: `payments-checkout-dev`, `fulfill-notify-prd`, `orders-inventory-stg`
 
 **Why this pattern?**
-- Simple and easy to understand.
-- Complies to [Temporal Cloud Namespace requirements](https://docs.temporal.io/cloud/namespaces#temporal-cloud-namespace-name)
-- Clearly separates environments (e.g., `dev`, `prod`)
-- Groups related services under domains that organization has defined
-- Allows for platform teams to implement chargeback to application teams, given most domains are owned by separate teams within organizations 
-- Namespace level [system limits](https://docs.temporal.io/cloud/limits#namespace-level) are isolated between different services and environments.
-- Multiple workflows that are part of the same use case need to communicate with each other via Signals or by starting Child Workflows.
+- Simple and easy to understand
+- Clearly separates environments
+- Groups related services under domains
+- Allows platform teams to implement chargeback to application teams
+- Namespace-level limits are isolated between different services and environments
+
+:::tip Temporal Cloud
+Cloud Namespace names are limited to [39 characters](/cloud/namespaces#temporal-cloud-namespace-name).
+If you need to include region, use short codes (e.g., `aps1`, `use1`).
+:::
+
+## Organizational Patterns
+
+### Pattern 1: Namespace per use case and environment
+
+For simple configurations without multiple services or team boundaries.
+
+**Naming convention**: `<use-case>_<environment>`
+
+**Example**: `payments_prod`, `orders_dev`
+
+### Pattern 2: Namespace per use case, service, and environment
+
+When multiple services that are part of the same use case communicate externally to Temporal via API (HTTP/gRPC).
+
+**Naming convention**: `<use-case>_<service>_<environment>`
+
+**Example**: `payments_gateway_prod`, `payments_processor_prod`
+
+### Pattern 3: Namespace per use case, domain, and environment
+
+When multiple services need to communicate with each other, use [Temporal Nexus](/nexus) to connect Workflows across Namespace boundaries.
+This provides better security, fault isolation, and modularity than sharing a Namespace.
+
+**Naming convention**: `<use-case>_<domain>_<environment>`
+
+**Example**: `payments_checkout_prod`, `payments_refunds_prod`
 
-  Note: [A Temporal Cloud account can have up to 100 Namespaces](https://docs.temporal.io/cloud/limits#namespaces) (soft limit).
+For systems without Nexus, services can communicate via [Signals](/sending-messages#sending-signals) or [Child Workflows](/child-workflows) within the same Namespace.
 
-#### 3. When selecting a region for your Namespace, choose one that aligns with your application's latency, compliance, and data residency requirements (use https://status.temporal.io/ to identify the right region for you).
+:::note Workflow ID uniqueness
+When multiple teams share a Namespace, prefix each Workflow ID with a service-specific string to ensure uniqueness.
+Task Queue names must also be unique within the Namespace.
+:::
 
-  Check out some more best practices for configuring Namespaces in [our documentation](https://docs.temporal.io/cloud/namespaces#general-guidance). 
+## Production Safeguards
 
-## Manage Namespaces
+### Use an Authorizer (open source only) {#authorizer}
 
-With Temporal, it’s important to be able to configure your Namespaces as well as see details for them. Whether you’re self-hosting or using Temporal Cloud, you’re able to get details for your Namespaces, update Namespace configuration, and deprecate or delete your Namespaces.
+Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your Frontend Service to set restrictions on who can create, update, or deprecate Namespaces.
 
-On Temporal Cloud, use the Temporal Cloud UI or `tcld` commands to manage Namespaces. We provide [guidance for both methods](https://docs.temporal.io/cloud/namespaces#manage-namespaces) in our docs that you can reference. 
+If an Authorizer is not set, Temporal uses the `nopAuthority` authorizer that unconditionally allows all API calls.
 
-Regardless of how you run Temporal, you must register a Namespace with the Temporal Service before setting it in the Temporal Client. 
+On Temporal Cloud, [role-based access controls](/cloud/users#namespace-level-permissions) provide namespace-level authorization without custom configuration.
 
-We recommend you use a custom [Authorizer](https://docs.temporal.io/self-hosted-guide/security#authorizer-plugin) on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces. If an Authorizer is not set in the server options, Temporal uses the nopAuthority authorizer that unconditionally allows all API calls to pass through.
+### Enable deletion protection (Temporal Cloud only) {#deletion-protection}
 
-### Best practices: 
+[Enable deletion protection](/cloud/namespaces#delete-protection) for production Namespaces to prevent accidental deletion.
 
-#### 1. Enable deletion protection for `prd` Namespaces: [Prevent accidental deletion](https://docs.temporal.io/cloud/namespaces#delete-protection) of production Namespaces.
+### Enable High Availability (Temporal Cloud only) {#high-availability}
 
-#### 2. Enable multi-region replication for business critical use cases: For many organizations, ensuring high availability (HA) is required because of strict uptime requirements, compliance, and regulatory needs. 
+For business-critical use cases with strict uptime requirements, enable [High Availability features](/cloud/high-availability) for a [99.99% contractual SLA](/cloud/high-availability#high-availability-features).
 
-  For these critical use cases, enable High Availability features for specific Namespaces for a [99.99% contractual SLA](https://docs.temporal.io/cloud/high-availability#high-availability-features). When choosing between [same-region and multi-region replication](https://docs.temporal.io/cloud/high-availability/how-it-works#deployment-options), favor multi-region replication to optimize reliability over proximity.
+### Use Infrastructure as Code (Temporal Cloud only) {#terraform}
 
-  By default, Temporal Cloud provides a [99.9% contractual SLA](https://docs.temporal.io/cloud/high-availability) guarantee against service errors for all Namespaces. 
+Use the [Temporal Cloud Terraform provider](/production-deployment/cloud/terraform-provider) to manage Namespaces.
+If Terraform isn't suitable, scripting against the [Cloud Ops API](/ops) or [tcld](/cloud/tcld) is a good alternative.
 
-  Note: [enabling HA features for Namespaces will 2x the consumption cost](https://docs.temporal.io/cloud/pricing#high-availability-features).
+This provides:
+- Documentation of each Namespace's purpose and owners
+- Prevention of infrastructure drift
+- Version-controlled configuration changes
 
-#### 3. Use Terraform to manage Namespaces:
-Use [Temporal Cloud Terraform provider](https://docs.temporal.io/production-deployment/cloud/terraform-provider) to manage Temporal Cloud Namespaces. This allows us to maintain documentation that outlines the purpose of each Namespace and their owners. In addition, Terraform enables us to prevent infrastructure drift (e.g. someone accidentally deletes a Namespace). 
+Use `prevent_destroy = true` in your Terraform configuration to prevent accidental Namespace deletion via Terraform.
+This is separate from [Temporal Cloud deletion protection](/cloud/namespaces#delete-protection), which prevents deletion through any interface.
 
-  Use `prevent_destroy = true` to prevent Terraform from destroying the Namespace. 
+**Reference**: [Example Terraform configuration](https://github.com/kawofong/temporal-terraform)
 
-  Reference: https://github.com/kawofong/temporal-terraform 
+## Tagging (Temporal Cloud only) {#tagging}
 
-## Tagging
+[Tags](/cloud/namespaces#tag-a-namespace) are key-value metadata pairs that help organize, track, and manage Namespaces.
 
-[Tags](https://docs.temporal.io/cloud/namespaces#tag-a-namespace) are key-value metadata pairs that can be attached to Namespaces in Temporal Cloud to help operators organize, track, and manage Namespaces more easily.
+Tags complement your naming convention by adding metadata that doesn't fit in the Namespace name.
+While the name captures use case, domain, and environment, tags can capture additional dimensions like team ownership, data sensitivity, or business criticality.
 
-### Tag Structure and Limits
-- Each Namespace can have a maximum of 10 tags
-- Each key must be unique for a given Namespace (e.g., a Namespace cannot have both `team:foo` and `team:bar` tags)
-- Keys and values must be 1-63 characters in length
-- Allowed characters: lowercase letters (a-z), numbers (0-9), periods (.), underscores (_), and hyphens (-)
-- Tags are not a secure storage mechanism and should not store PII or PHI
-- Tags will not change the behavior of the tagged resource
-- There is a soft limit of 1000 unique tag keys per account
+### Recommended tag categories
 
-We also recommend tagging your Namespaces based on the following criteria: 
-- Environment
-- Latency sensitivity
-- Business criticality: regulatory, user-facing
-- Data sensitivity
-- Team or Project
-- Division
+| Tag Key | Purpose | Examples |
+|---------|---------|----------|
+| `environment` | Deployment stage | `dev`, `staging`, `production` |
+| `team` | Owning team | `platform`, `payments`, `identity` |
+| `division` | Business unit | `engineering`, `finance`, `ops` |
+| `criticality` | Business importance | `high`, `medium`, `low` |
+| `data-sensitivity` | Data classification | `pii`, `pci`, `public` |
+| `latency-sensitivity` | Performance tier | `realtime`, `batch`, `async` |
 
-## Setting
+For tag structure, limits, and management instructions, see [How to tag a Namespace](/cloud/namespaces#tag-a-namespace).
 
-Temporal Cloud provides a few configurable parameters associated with a Namespace, client, or service that determines how Temporal behaves for that scope. You can configure many of these settings when creating or editing a Namespace via the UI or CLI (`tcld`).
+## SDK Client Configuration
 
-You must also set Namespaces in your SDK Client to isolate your Workflow Executions to the Namespace. If you do not set a Namespace, all Workflow Executions started using the Client will be associated with the `default` Namespace. This means, you must have a default Namespace called `default` registered with your Temporal Service.
+Set Namespaces in your SDK Client to isolate your Workflow Executions.
+If you do not set a Namespace, all Workflow Executions started using the Client will be associated with the `default` Namespace.
 
-Here are some of the typical Namespace settings you’re able to configure:
+You must register a Namespace before setting it in your Client.
 
-| Setting | Description |
-|---------|-------------|
-| `namespace` (SDK/client) | The name of the Namespace your client is scoped to |
-| `retention` | How long workflow execution history is kept |
-| `certificate` | The client certificate used for mTLS authentication |
-| `codec_server_endpoint` | URL to a Codec Server for decrypting encrypted payloads in the UI |
-| `default_task_queue` | The task queue used if none is specified in the workflow code |
-| `search_attributes` | Custom fields that allow filtering and querying workflow executions |
-| `data_converter` | Used to serialize/deserialize and encrypt/decrypt workflow payloads |
-| `visibility settings` | Controls how workflow status data is indexed and queried |
+For configuration details, see:
+- [Namespace concepts](/namespaces)
+- [Namespaces (Temporal Cloud)](/cloud/namespaces#access-namespaces)