chore: Add module examples to User Management Guide and apply consistency in docs

docs/guides/atlas-user-management.md

@@ -519,96 +519,16 @@ The legacy `mongodbatlas_team.usernames` list maps to individual
 cannot be used. Existing team memberships must be imported.
 
 - **Module maintainers**
-  - Define `mongodbatlas_cloud_user_team_assignment` inside the module.
-  - Example **old** module implementation:
-    ```terraform
-      variable "org_id"    { type = string }
-    variable "team_name" { type = string }
-    variable "usernames" { type = list(string) }
-
-    resource "mongodbatlas_team" "this" {
-      org_id    = var.org_id
-      name      = var.team_name
-      usernames = var.usernames  # deprecated
-    }
-    ```
-  - Example **new** module implementation:
-    ```terraform
-    variable "org_id"    { type = string }
-    variable "team_name" { type = string }
-    variable "user_ids"  { type = set(string) }
-
-    resource "mongodbatlas_team" "this" {
-      org_id = var.org_id
-      name   = var.team_name
-      # removed deprecated usernames
-    }
-
-    resource "mongodbatlas_cloud_user_team_assignment" "this" {
-      for_each = var.user_ids
-
-      org_id   = var.org_id
-      team_id  = mongodbatlas_team.this.team_id
-      user_id  = each.value
-    }
-    ```
-  - Terraform doesn’t allow import blocks in the module ([Terraform issue](https://github.com/hashicorp/terraform/issues/33474)). Document the import ID formats for users:
-      - Team assignment: `org_id/team_id/user_id` (or `org_id/team_id/username`)
+  - Replace the deprecated `usernames` attribute with `mongodbatlas_cloud_user_team_assignment` resources inside the module.
+  - Terraform doesn't allow import blocks in modules ([Terraform issue](https://github.com/hashicorp/terraform/issues/33474)). Document the import ID format for users: `org_id/team_id/user_id` (or `org_id/team_id/username`).
   - Publish a new module version.
+  - See [module_maintainer example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_user_team_assignment/module_maintainer) for complete implementation.
 
 - **Module users**
-  - Upgrade to the new module version (`terraform init -upgrade`) and run terraform plan but **do not apply**.
-  - Example **old** module usage (using deprecated resources):
-    ```hcl
-    module "user_team_assignment" {  
-      source     = "./old_module"  
-      org_id     = var.org_id  
-      team_name  = var.team_name  
-      usernames  = var.usernames 
-    }
-    ```
-  - Example **new** module usage:
-    ```hcl
-    data "mongodbatlas_team" "this" {  
-      org_id = var.org_id  
-      name   = var.team_name
-    }
-
-    locals {  
-      user_ids = toset([
-        for user in data.mongodbatlas_team.this.users : user.id
-      ]) 
-    }
-
-    module "user_team_assignment" {
-      source     = "./new_module"
-      org_id     = var.org_id
-      team_name  = var.team_name
-      user_ids = local.user_ids   # replaced deprecated usernames
-    }
-    ```
-  - Add an `import block` (or `terraform import`) to import the resources and iterate through the list of users:
-    ```terraform
-    import { 
-        for_each = local.team_assignments
-        to       = module.user_team_assignment.mongodbatlas_cloud_user_team_assignment.this[each.key]
-        id       = "${var.org_id}/${data.mongodbatlas_team.this.team_id}/${each.value}"
-    }
-    ```
-  - Run `terraform plan` to review the changes.
-      - Ensure that Terraform imports the user-team assignments and does not plan to create these.
-      - Ensure that Terraform does not plan to modify the `mongodbatlas_team` resource.
-  - Run `terraform apply` to apply the migration.
-
-For complete working examples, see:
-
-- [Old module definition](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.0.0/examples/migrate_user_team_assignment/module_maintainer/v1)
-  and
-  [old module usage](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.0.0/examples/migrate_user_team_assignment/module_user/v1).
-- [New module definition](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.0.0/examples/migrate_user_team_assignment/module_maintainer/v2)
-  and
-  [new module usage](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.0.0/examples/migrate_user_team_assignment/module_user/v2).
-- [mongodbatlas_cloud_user_team_assignment](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.0.0/examples/mongodbatlas_cloud_user_team_assignment/main.tf).
+  - Upgrade to the new module version (`terraform init -upgrade`) and run `terraform plan` but **do not apply**.
+  - Add `import` blocks (or use `terraform import`) for each existing team assignment.
+  - Run `terraform plan` to confirm import operations, then `terraform apply`.
+  - See [module_user example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_user_team_assignment/module_user) for complete implementation.
 
 ---
 
@@ -808,20 +728,17 @@ Keep
   - Re-run `terraform plan` to confirm import operations, then `terraform apply`.
 
 
+- See [module_maintainer example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_team_project_assignment/module_maintainer) for complete implementation.
+- See [module_user example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_team_project_assignment/module_user) for complete implementation.
+
 ---
 
 ### Examples
 
-For complete, working configurations that demonstrate the migration process, see
-the examples in the provider repository:
-[migrate_team_project_assignment](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_team_project_assignment).
-
-The examples include:
-
-- **v1**: Original configuration using deprecated `teams` attribute in
-  `mongodbatlas_project` resource.
-- **v2**: Final configuration using `mongodbatlas_team_project_assignment`
-  resource for team-to-project assignments.
+For complete, working examples that demonstrate the migration process, see:
+- Basic usage (v1–v2): [basic](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_team_project_assignment/basic)
+- Module maintainer (v1–v3): [module_maintainer](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_team_project_assignment/module_maintainer)
+- Module user (v1–v3): [module_user](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_team_project_assignment/module_user)
 
 ---
 
@@ -920,31 +837,23 @@ Run `terraform apply` to create the assignment with the new resource & delete th
   - Keep inputs consistent (`project_id`, `username`, `roles`) so the new resource re-creates the pending invite with the same roles.
   - Remove the deprecated `mongodbatlas_project_invitation` resource block from the module.
   - Publish a new module version.
+  - See [module_maintainer example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_project_invitation_to_cloud_user_project_assignment/module_maintainer) for complete implementation.
 
 - **Module users**
   - Upgrade to the new module version and run `terraform plan`.
   - Expect to see planned creation `mongodbatlas_cloud_user_project_assignment` and deletion of `mongodbatlas_project_invitation`.
   - Run `terraform apply`.
+  - See [module_user example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_project_invitation_to_cloud_user_project_assignment/module_user) for complete implementation.
 
 ---
 
 ### Examples
 
-For complete, working configurations that demonstrate the migration process, see
-the examples in the provider repository:
-[migrate_project_invitation_to_cloud_user_project_assignment](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.0.0/examples/migrate_project_invitation_to_cloud_user_project_assignment).
+For complete, working configurations that demonstrate the migration process, see:
 
-The examples include:
-
-- **v1**: Original configuration using deprecated
-  `mongodbatlas_project_invitation`
-- **v2**: Migration phase with re-creation using new resource and clean state
-  removal
-- **v3**: Final clean configuration using only
-  `mongodbatlas_cloud_user_project_assignment`
-
-These examples provide practical validation of the migration steps and
-demonstrate the re-creation approach for pending invitations.
+- Basic usage (v1–v3): [basic](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_project_invitation_to_cloud_user_project_assignment/basic)
+- Module maintainer (v1–v3): [module_maintainer](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_project_invitation_to_cloud_user_project_assignment/module_maintainer)
+- Module user (v1–v3): [module_user](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_project_invitation_to_cloud_user_project_assignment/module_user)
 
 ---
 
@@ -1204,33 +1113,27 @@ Run `terraform plan` to ensure no unexpected changes, then `terraform apply`.
 Since data sources don’t live in state, in this case migration is about replacing data sources and updating attribute references (and, if needed, module inputs/outputs).
 
 - **Module maintainers**
-  - Replace deprecated data sources with the new resources as mentioned in above steps.
+  - Replace deprecated data sources with the new data sources as mentioned in above steps.
   - Update attribute references as mentioned above.
   - Publish a new module version.
+  - See [module_maintainer example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_atlas_user_and_atlas_users/module_maintainer) for complete implementation.
 
 - **Module users**
   - Upgrade to the new module version and run `terraform plan`.
-  - Update your references to the module’s outputs/variables to match the new attribute structure (use the mapping above).
+  - Update your references to the module's outputs/variables to match the new attribute structure (use the mapping above).
   - Re-run `terraform plan` to confirm reads succeed and the output shape is as expected, then proceed as usual.
-
+  - See [module_user example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_atlas_user_and_atlas_users/module_user) for complete implementation.
 
 
 ---
 
 ### Examples
 
-For complete, working configurations that demonstrate the migration process, see
-the examples in the provider repository:
-[migrate_atlas_user_and_atlas_users](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.0.0/examples/migrate_atlas_user_and_atlas_users).
-
-The examples include:
-
-- **v1**: Original configuration using deprecated data sources
-- **v2**: Migration phase with side-by-side comparison and validation
-- **v3**: Final clean configuration using only new data sources
+For complete, working configurations that demonstrate the migration process, see:
 
-These examples provide practical validation of the migration steps and
-demonstrate the attribute mappings in working Terraform code.
+- Basic usage (v1–v3): [basic](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_atlas_user_and_atlas_users/basic)
+- Module maintainer (v1–v3): [module_maintainer](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_atlas_user_and_atlas_users/module_maintainer)
+- Module user (v1–v3): [module_user](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_atlas_user_and_atlas_users/module_user)
 
 ---
 

examples/migrate_atlas_user_and_atlas_users/README.md

@@ -1,55 +1,12 @@
 # Migration Example: Atlas User to Cloud User Org Assignment
 
-This example demonstrates how to migrate from the deprecated `mongodbatlas_atlas_user` and `mongodbatlas_atlas_users` data sources to their replacements.
+This example demonstrates migrating from the deprecated `mongodbatlas_atlas_user` and `mongodbatlas_atlas_users` data sources to their replacements.
 
-## Migration Phases
+## Basic usage (direct data source usage)
 
-### v1: Initial State (Deprecated Data Sources)
-Shows the original configuration using deprecated data sources:
-- `mongodbatlas_atlas_user` for single user reads
-- `mongodbatlas_atlas_users` for user lists
+- [basic](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_atlas_user_and_atlas_users/basic): Direct data source usage.
 
-### v2: Migration Phase (Both Old and New)
-Demonstrates the migration approach:
-- Adds new data sources alongside old ones
-- Shows attribute mapping examples
-- Validates new data sources work before removing old ones
+## Module-based examples
 
-### v3: Final State (New Data Sources Only)
-Clean final configuration using only:
-- `mongodbatlas_cloud_user_org_assignment` for single user reads
-- `mongodbatlas_organization.users`, `mongodbatlas_project.users`, `mongodbatlas_team.users` for user lists
-
-## Usage
-
-1. Start with v1 to understand the original setup
-2. Apply v2 configuration to add new data sources
-3. Verify the new data sources return expected data
-4. Update your references using the attribute mappings shown
-5. Apply v3 configuration for the final clean state
-
-## Prerequisites
-
-- MongoDB Atlas Terraform Provider 2.0.0 or later
-- Valid MongoDB Atlas organization, project, and team IDs
-- Existing users in your organization
-
-## Variables
-
-Set these variables for all versions:
-
-```terraform
-client_id     = "<ATLAS_CLIENT_ID>"   # Optional, can use env vars
-client_secret = "<ATLAS_CLIENT_SECRET>" # Optional, can use env vars
-org_id     = "your-organization-id"
-project_id = "your-project-id"  
-team_id    = "your-team-id"
-user_id    = "existing-user-id"
-username   = "[email protected]"
-```
-
-Alternatively, set environment variables:
-```bash
-export MONGODB_ATLAS_CLIENT_ID="<ATLAS_CLIENT_ID>"
-export MONGODB_ATLAS_CLIENT_SECRET="<ATLAS_CLIENT_SECRET>"
-```
+- [module_maintainer](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_atlas_user_and_atlas_users/module_maintainer): How module maintainers should migrate.
+- [module_user](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_atlas_user_and_atlas_users/module_user): How module consumers should migrate.

examples/migrate_atlas_user_and_atlas_users/basic/README.md

@@ -0,0 +1,74 @@
+# Basic Migration Example: Atlas User Data Sources
+
+This example demonstrates how to migrate from the deprecated `mongodbatlas_atlas_user` and `mongodbatlas_atlas_users` data sources to their replacements.
+
+For migration steps, see the [Migration Guide](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/docs/guides/atlas-user-management.md).
+
+### v1: Initial State (Deprecated Data Sources)
+
+Shows the original configuration using deprecated data sources:
+- `mongodbatlas_atlas_user` for single user reads
+- `mongodbatlas_atlas_users` for user lists
+
+### v2: Migration Phase
+
+Runs both old and new data sources side-by-side to validate the migration.
+
+**Key comparisons:**
+- Single user: `email_address` → `username`
+- Single user: Complex role filtering → Structured `roles.org_roles` and `roles.project_role_assignments`
+- User lists: `results[*].email_address` → `users[*].username`
+
+**Usage:**
+1. Apply this configuration: `terraform apply`
+2. Review the comparison outputs to verify data consistency
+3. Check `migration_validation.ready_for_v3` is `true`
+4. Once validated, proceed to v3
+
+**Expected outputs:** Side-by-side comparisons of email retrieval methods, role access patterns, user list structures, and count validations.
+
+### v3: Final State (New Data Sources Only)
+
+Clean final configuration using only:
+- `mongodbatlas_cloud_user_org_assignment` for single user reads
+- `mongodbatlas_organization.users`, `mongodbatlas_project.users`, `mongodbatlas_team.users` for user lists
+
+**Key improvements:**
+- **Structured roles**: Organization and project roles are clearly separated
+- **Direct access**: No need to filter consolidated role lists
+- **Consistent naming**: `username` instead of `email_address`
+- **Better organization**: User lists come from their natural containers (org/project/team)
+- **Better performance**: Organization context required for user reads (more efficient API calls)
+
+## Usage
+
+1. Start with v1 to understand the original setup
+2. Apply v2 to validate new data sources return expected data
+3. Apply v3 for the final clean state
+
+## Prerequisites
+
+- MongoDB Atlas Terraform Provider 2.0.0 or later
+- Valid MongoDB Atlas organization, project, and team IDs
+- Existing users in your organization
+
+## Variables
+
+Set these variables for all versions:
+
+```terraform
+client_id     = "<ATLAS_CLIENT_ID>"      # Optional, can use env vars
+client_secret = "<ATLAS_CLIENT_SECRET>"  # Optional, can use env vars
+org_id        = "your-organization-id"
+project_id    = "your-project-id"  
+team_id       = "your-team-id"
+user_id       = "existing-user-id"
+username      = "[email protected]"
+```
+
+Alternatively, set environment variables:
+
+```bash
+export MONGODB_ATLAS_CLIENT_ID="<ATLAS_CLIENT_ID>"
+export MONGODB_ATLAS_CLIENT_SECRET="<ATLAS_CLIENT_SECRET>"
+```

examples/migrate_atlas_user_and_atlas_users/module_maintainer/README.md

@@ -0,0 +1,27 @@
+# Module Maintainer Migration Example
+
+This example demonstrates how module maintainers should migrate from the `mongodbatlas_atlas_user` data source to `mongodbatlas_cloud_user_org_assignment`.
+
+For migration steps, see the [Migration Guide](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/docs/guides/atlas-user-management.md).
+
+## v1: Initial State
+
+Module using the deprecated `mongodbatlas_atlas_user` data source:
+- Complex role filtering with `for` expressions
+- Separate `email_address` and `username` attributes
+- Outputs: user_id, username, email_address, first_name, last_name, org_roles, project_roles
+
+## v2: Migration
+
+- Replace `mongodbatlas_atlas_user` with `mongodbatlas_cloud_user_org_assignment`
+- Simplified role access via `roles.org_roles` (no filtering needed for org roles)
+- `email_address` now returns `username`
+- Output names kept the same
+
+See `module_user/v2` for an example of how to consume this module.
+
+## v3: Cleaned Up Configuration
+
+Final module definition after migration is complete:
+- Uses `mongodbatlas_cloud_user_org_assignment` data source
+- Same outputs as v1/v2