Updated with Dhruv's feedback'

Author: RoseHJM

articles/dev-box/concept-what-are-team-customizations.md

@@ -5,7 +5,7 @@ author: RoseHJM
 ms.author: rosemalcolm
 ms.service: dev-box
 ms.topic: concept-article
-ms.date: 11/05/2024
+ms.date: 11/06/2024
 
 #customer intent: As a Project Admin or Dev Center Admin, I want to understand how to use Dev Box Team Customizations so that I can create efficient, ready-to-code configurations for my development teams.
 ---
@@ -32,9 +32,9 @@ When you configure Dev Box Team Customizations for your organization, careful pl
     - Add tasks.
     - Attach to dev center or project.
 - **Create a team customizations file:**
-  - Create a team customizations file called definition.yaml.
+  - Create a team customizations file called imagedefinition.yaml.
 - **Specify image in a dev box pool:**
-  - Create or modify a dev box pool and specify definition.yaml as the image definition.
+  - Create or modify a dev box pool and specify imagedefinition.yaml as the image definition.
 - **Choose how you'll use the image definition:**
     - Optimize for team customization.
     - Build each time you create a dev box.
@@ -47,10 +47,12 @@ Dev Box customizations use a yaml formatted file to specify a list of tasks to a
 You can use secrets from your Azure Key Vault in your customization file to clone private repositories, or with any custom task you author that requires an access token.
 
 ## What are tasks?
-Dev Box customization tasks are wrappers for PowerShell scripts, allowing you as a platform team to define reusable components that your teams can use in their customizations. WinGet and PowerShell are available as primitive tasks out of the box
+Dev Box customization tasks are wrappers for PowerShell scripts, allowing you as a platform team to define reusable components that your teams can use in their customizations. WinGet and PowerShell are available as primitive tasks out of the box.
+
+When creating tasks, determine which need to run in a SYSTEM context and which can run after sign-in, in a user context. Team customizations can be run in a SYSTEM context and in a user context (after sign-in). Individual customizations can only run in a user context. 
 
 ## Differences Between Team and Individual Customizations
-Individual developers can attach a yaml-based customization file when creating their Dev Box to control the development environment on their Dev Box. An individual customization file should be used only for personal settings and apps. While teams of developers can share common yaml files, this approach can be inefficient and error-prone, and against compliance policies. Dev Box Team Customizations provides a workflow for developer team leaders, Project Admins, and dev center administrators to preconfigure customization files on Dev Box pools. This way, a developer creating a dev box doesn't need to find and upload a customization file for themselves.
+Individual developers can attach a yaml-based customization file when creating their Dev Box to control the development environment on their Dev Box. Individual customizations should be used only for personal settings and apps. Tasks specified in the individual customization file run only in the user context, after sign-in. While teams of developers can share common yaml files, this approach can be inefficient and error-prone, and against compliance policies. Dev Box Team Customizations provides a workflow for developer team leaders, Project Admins, and dev center administrators to preconfigure customization files on Dev Box pools. This way, a developer creating a dev box doesn't need to find and upload a customization file for themselves.
 
 ## Key terms
 When working with Dev Box Team Customizations, you should be familiar with the following key terms:
@@ -64,7 +66,7 @@ When working with Dev Box Team Customizations, you should be familiar with the f
     - Consist of one or more PowerShell scripts and a task.yaml file.
 - **Customization file**
     - Yaml-based file defining tasks for dev boxes.
-    - When shared across a team, it's called an *image definition* and specifies OS, compute, and storage.
+    - When shared across a team, it's an *image definition* and specifies the base dev box image, along with its customization options.
 
 ## Related content
 - [Quickstart: Create Dev Box Team Customizations](quickstart-team-customizations.md)

articles/dev-box/how-to-configure-customization-imaging.md

@@ -69,11 +69,11 @@ On the Image definition page, you see the image definitions accessible to your p
 
 :::image type="content" source="media/how-to-configure-customization-imaging/team-customizations-image-definitions-small.png" alt-text="Screenshot of the Image definition pane in the Azure portal, showing accessible image definitions for a project." lightbox="media/how-to-configure-customization-imaging/team-customizations-image-definitions.png":::
 
-
+For more information about attaching catalogs, see [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md).
 
 ## Configure a dev box pool to use an image definition
 
-Make customizations available to your development teams by configuring a dev box pool to use a customization file (*definition.yaml*). Store the customization file in a repository linked to a catalog in your dev center or project. Specify this file as the image definition for the pool, and the customizations are applied to new dev boxes.
+Make customizations available to your development teams by configuring a dev box pool to use a customization file (*imagedefinition.yaml*). Store the customization file in a repository linked to a catalog in your dev center or project. Specify this file as the image definition for the pool, and the customizations are applied to new dev boxes.
 
 The following steps show you how to create a dev box pool and specify an image definition. 
 

articles/dev-box/how-to-create-customization-tasks-catalog.md

@@ -54,7 +54,7 @@ To create and manage tasks for Dev Box Team Customizations, follow these steps:
 1. Create a configuration file for those tasks by following the steps in [Write a customization file](./how-to-write-customization-file.md).
 
 ### Use secrets from an Azure Key Vault
-You can use secrets from your Azure Key Vault in your yaml configurations to clone private repositories, or with any custom task you author that requires an access token.
+You can use secrets from your Azure Key Vault in your yaml configurations to clone private repositories, or with any custom task you author that requires an access token. Your dev center needs access to your key vault. DevCenter does not support service tags, so if your key vault is kept private you must allow trusted Microsoft services to bypass the firewall.
 
 To configure your Key Vault secrets for use in your yaml configurations,
 

articles/dev-box/how-to-write-customization-file.md

@@ -5,7 +5,7 @@ author: RoseHJM
 ms.author: rosemalcolm
 ms.service: dev-box
 ms.topic: how-to
-ms.date: 11/05/2024
+ms.date: 11/06/2024
 
 #customer intent: As a dev center administrator or DevCenter Project Admin I want to create image definition files so that my development teams can create customized dev boxes.
 ---
@@ -57,7 +57,7 @@ There are two ways to use a customization file: team customizations which apply
 - Contain tasks that are applied when a dev box is created.
 - Are shared across a team or project.
 - Include a field that specifies the base image.
-- Are named *definition.yaml*.
+- Are named *imagedefinition.yaml*.
 - Are uploaded to the repository that hosts your catalog.
 - Are automatically used when you create a dev box from a configured pool. 
 
@@ -67,7 +67,7 @@ There are two ways to use a customization file: team customizations which apply
 
 ## Create a customization file
 
-You can create and manage customization files with Visual Studio Code. You can use a Visual Studio Code extension to discover the tasks in the attached catalog, and test the customization file in Visual Studio Code.
+You can create and manage customization files with Visual Studio Code. You can use the [Microsoft Dev Box Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=DevCenter.ms-devbox) to discover the tasks in the attached catalog, and test the customization file in Visual Studio Code.
 
 1. Create a Dev Box (or use an existing Dev Box) for testing.
 1. On the test dev box, install Visual Studio Code and then install the [Dev Box VS Code extension](https://aka.ms/devbox/preview/customizations/vsc-extension).
@@ -122,7 +122,8 @@ To invoke the Dev Box chat agent:
 
 ## Use secrets from an Azure Key Vault
 You can use secrets from your Azure Key Vault in your yaml customizations to clone private repositories, or with any custom task you author that requires an access token.
-To configure your Key Vault secrets for use in your yaml customizations,
+
+To configure your Key Vault secrets for use in your yaml customizations:
 1. Ensure that your dev center project's managed identity has the Key Vault Reader role and Key Vault Secrets User role on your key vault.
 2. Grant the Secrets User role for the Key Vault secret to each user or user group who should be able to consume the secret during the customization of a dev box. The user or group granted the role must include the managed identity for the dev center, your own user account, and any user or group who needs the secret during the customization of a dev box.
 
@@ -155,7 +156,7 @@ tasks:
          pat: '{{ado://YOUR_ADO_ORG}}'
 ```
 
-If your organization's policies require you to keep your Key Vault private from the internet, you can set your Key Vault to allow trusted Microsoft services to bypass your firewall rule.
+Your dev center needs access to your key vault. DevCenter does not support service tags, so if your key vault is kept private you must allow trusted Microsoft services to bypass the firewall. 
 
 :::image type="content" source="media/how-to-write-customization-file/trusted-services-bypass-firewall.png" alt-text="text":::
 
@@ -175,7 +176,7 @@ tasks:
 To learn more about WinGet Configuration, see [WinGet Configuration](https://aka.ms/winget-configuration).
 
 ## Share a customization file from a code repository
-Make your customization file available to dev box pools by naming it *definition.yaml* and uploading it to the repository that hosts your catalog. When you create a dev box pool, you can select the customization file from the catalog to apply to the dev boxes in the pool.
+Make your customization file available to dev box pools by naming it *imagedefinition.yaml* and uploading it to the repository that hosts your catalog. When you create a dev box pool, you can select the customization file from the catalog to apply to the dev boxes in the pool.
 
 ## Related content
 - [Microsoft Dev Box Team Customizations](concept-what-are-team-customizations.md)