Tidy up enterprise managed-settings.json docs (#62197)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com>

Author: 3 people

content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings.md

@@ -21,6 +21,10 @@ These settings apply enterprise-wide, with no organization-level override. For e
 
 Managed settings are loaded locally when the client starts, even if the device has no network connection. This means controls such as disabled bypass mode and restricted plugin configuration still apply before sign in or any server round trip, and remain active when users switch accounts.
 
+## Defining settings
+
+For detailed information on the available properties and syntax, see [AUTOTITLE](/copilot/reference/enterprise-managed-settings-reference).
+
 ## Choosing a deployment method
 
 There are multiple ways to deploy enterprise managed settings. Use the following guidelines to choose the right method for you. For any method, pilot on a small device group before broad deployment.
@@ -55,121 +59,6 @@ There are multiple ways to deploy enterprise managed settings. Use the following
 1. Ask users to restart supported clients so the updated policy is loaded at startup.
 1. Confirm the settings took effect. See [Verifying the configuration has applied](#verifying-the-configuration-has-applied).
 
-## Consolidated schema reference
-
-The `{% data variables.copilot.managed_setting_file %}` file supports the following top-level properties. You can include any combination of these properties based on which settings you want to enforce.
-
-```json copy
-{
-  "extraKnownMarketplaces": {
-    "agent-skills": {
-      "source": {
-        "source": "github",
-        "repo": "OWNER/REPO"
-      }
-    }
-  },
-  "strictKnownMarketplaces": [
-    {
-      "source": "github",
-      "repo": "OWNER/REPO"
-    }
-  ],
-  "enabledPlugins": {
-    "PLUGIN-NAME@MARKETPLACE-NAME": true
-  },
-  "permissions": {
-    "disableBypassPermissionsMode": "disable"
-  },
-  "model": "auto"
-}
-```
-
-* `extraKnownMarketplaces`: Defines additional plugin marketplaces available to users. Each entry is a named marketplace object containing a `source` property that specifies the provider (`"github"`) and the repository in `OWNER/REPO` format.
-* `strictKnownMarketplaces`: Restricts plugin installation to only the marketplaces explicitly defined by the enterprise. Each entry is a marketplace object containing a `source` property. The `source` specifies the provider as either `"github"` with a `repo` in `OWNER/REPO` format, or `"git"` with a `url` pointing to a git repository.
-* `enabledPlugins`: Defines plugins that are automatically installed for all enterprise users. Each entry uses the format `PLUGIN-NAME@MARKETPLACE-NAME` as the key, with a boolean value of `true` to enable the plugin.
-* `permissions`: Controls whether users can bypass command approval. Set `disableBypassPermissionsMode` to `"disable"` to prevent users from turning on bypass mode. See [Disabling bypass mode for your enterprise](#disabling-bypass-mode-for-your-enterprise) further in this article for more information.
-* `model`: Controls default model governance settings. Set to `"auto"` so new conversations start with Copilot auto model selection by default. Users can still switch to a different model on a per-conversation basis.
-
-## Configuring enterprise plugin standards
-
-You can apply settings to control users' available plugin marketplaces and default-installed plugins. See [AUTOTITLE](/copilot/concepts/agents/about-enterprise-plugin-standards).
-
-{% data reusables.copilot.create-managed-settings %}
-1. Add the `extraKnownMarketplaces`, `strictKnownMarketplaces`, and `enabledPlugins` properties you need to the file. See the example and property descriptions in [Consolidated schema reference](#consolidated-schema-reference). Merge these properties into an existing file rather than overwriting it, so you don't remove settings configured for other policies, such as `permissions`.
-
-   ```json copy
-   {
-     "extraKnownMarketplaces": {
-       "agent-skills": {
-         "source": {
-           "source": "github",
-           "repo": "OWNER/REPO"
-         }
-       }
-     },
-     "strictKnownMarketplaces": [
-       {
-         "source": "github",
-         "repo": "OWNER/REPO"
-       }
-     ],
-     "enabledPlugins": {
-       "PLUGIN-NAME@MARKETPLACE-NAME": true
-     }
-   }
-   ```
-
-1. Commit and push your changes to the default branch of the `.github-private` repository.
-
-## Setting {% data variables.product.prodname_copilot_short %} auto model selection as the default
-
-You can set auto model selection as the default model for new conversations in {% data variables.copilot.copilot_cli_short %} and {% data variables.product.prodname_vscode_shortname %}. To learn more see [AUTOTITLE](/copilot/concepts/models/auto-model-selection). By setting it as the default for your enterprise, you ensure new conversations start with Auto model selected.
-
-### What setting Auto model as the default does
-
-When you `model` to `"auto"`, new conversations start with Auto model selected in both clients:
-
-* In {% data variables.copilot.copilot_cli_short %}, new sessions use Auto model unless the user specifies a different model.
-* In {% data variables.product.prodname_vscode_shortname %}, the model picker defaults to Auto model when a user starts a new conversation.
-
-Users can still switch to a different model on a per-conversation basis.
-
-### Configuring the setting
-
-{% data reusables.copilot.create-managed-settings %}
-1. Add the `model` property to the file, set to `"auto"`.
-
-   ```json copy
-   {
-     "model": "auto"
-   }
-   ```
-
-## Disabling bypass mode for your enterprise
-
-You can prevent users from enabling bypass mode (also known as "YOLO mode") in {% data variables.copilot.copilot_cli_short %} and {% data variables.product.prodname_vscode_shortname %}. Bypass mode lets an agent run commands, access files, and fetch URLs without asking for approval. By disabling it for your enterprise, you ensure that a person reviews each of these actions.
-
-### What disabling bypass mode prevents
-
-When you set `disableBypassPermissionsMode` to `"disable"`, users cannot turn on bypass mode in either client:
-
-* In {% data variables.copilot.copilot_cli_short %}, the `--yolo`, `--allow-all`, `--allow-all-tools`, `--allow-all-paths`, and `--allow-all-urls` command-line options and the `/yolo` and `/allow-all` slash commands are blocked.
-* In {% data variables.product.prodname_vscode_shortname %}, the global auto-approve setting (`chat.tools.global.autoApprove`), also known as "YOLO mode," is turned off and cannot be re-enabled.
-
-### Configuring the setting
-
-{% data reusables.copilot.create-managed-settings %}
-1. Add the `permissions` property to the file, with `disableBypassPermissionsMode` set to `"disable"`. If the file already has a `permissions` object (for example, from other permission settings), merge this key into it rather than replacing the object.
-
-   ```json copy
-   {
-     "permissions": {
-       "disableBypassPermissionsMode": "disable"
-     }
-   }
-   ```
-
 ## Verifying the configuration has applied
 
 Once the configuration is committed, users on a supported client see the specified settings within about an hour, since clients periodically check the server for updated configuration. Restarting the client or signing in again applies the latest settings immediately.

content/copilot/reference/copilot-cli-reference/cli-command-reference.md

@@ -1008,6 +1008,8 @@ OTel is off by default with zero overhead. It activates when any of the followin
 * `OTEL_EXPORTER_OTLP_ENDPOINT` is set
 * `COPILOT_OTEL_FILE_EXPORTER_PATH` is set
 
+OTel configuration can also be set in {% data variables.product.prodname_vscode_shortname %}, or in an enterprise-wide `{% data variables.copilot.managed_setting_file %}` file. See [Enable OTel monitoring](https://code.visualstudio.com/docs/agents/guides/monitoring-agents#_enable-otel-monitoring) in the {% data variables.product.prodname_vscode_shortname %} documentation and [AUTOTITLE](/copilot/reference/enterprise-managed-settings-reference).
+
 ### OTel environment variables
 
 | Variable | Default | Description |

content/copilot/reference/enterprise-managed-settings-reference.md

@@ -9,36 +9,31 @@ category:
   - Configure Copilot
 ---
 
-> [!NOTE]
-> This feature is in {% data variables.release-phases.public_preview %} and subject to change.
-
 Use this reference to understand the currently supported keys in `{% data variables.copilot.managed_setting_file %}`.
 
 For deployment methods, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings#choosing-a-deployment-method).
 
 ## Precedence rules
 
-When multiple settings sources are present, clients apply settings in this order:
+When multiple settings sources are present, settings earlier in this list take precedence over settings later in the list:
 
-1. Server-managed settings
 1. MDM-managed settings
+1. Server-managed settings
 1. File-based settings
 1. User-level settings
 
-MDM-managed settings take precedence. If MDM-managed settings are not available, clients apply server-managed settings before file-based settings.
-
 ## Supported keys
 
 {% rowheaders %}
 
 | Key | Type | Accepted values | Purpose |
 | --- | --- | --- | --- |
 | `permissions.disableBypassPermissionsMode` | `string` | `"disable"` | Disables bypass or YOLO-style allow-all behavior |
-| `enabledPlugins` | `object` | Key format: `PLUGIN-NAME@MARKETPLACE-NAME`; value: `true` | Enables specific plugins by key |
-| `extraKnownMarketplaces` | `object` | Named marketplace object with `source.source` (`"github"`) and `source.repo` (`OWNER/REPO`) | Adds plugin marketplaces that users can access |
-| `strictKnownMarketplaces` | `array` | Array of marketplace objects with `source` values (`"github"` with `repo`, or `"git"` with `url`) | Restricts plugin installation to explicitly listed marketplaces |
-| `model` | `object` | `default` set to a supported model name | Defines default model governance settings |
-| `telemetry` | `object` | `enabled` (`boolean`), `endpoint` (`string`), `protocol` (`"otlp-http"` or `"otlp-grpc"`), `captureContent` (`boolean`), `lockCaptureContent` (`boolean`), `serviceName` (`string`), `resourceAttributes` (`object`), `headers` (`object`) | Configures OpenTelemetry export for {% data variables.product.prodname_vscode_shortname %} |
+| `permissions.model` | `string` | `"auto"` | Sets auto model selection as the default for new conversations|
+| `enabledPlugins` | `object` | Key format: `PLUGIN-NAME@MARKETPLACE-NAME`; value: `true` (enable) or `false` (disable) | Enables or disables specific plugins by key |
+| `extraKnownMarketplaces` | `object` | Named marketplace objects; supported source types: `"github"`, `"git"`, `"directory"` | Adds plugin marketplaces that users can access |
+| `strictKnownMarketplaces` | `array` | Array of marketplace objects; supported source types: `"github"`, `"git"`, `"url"`, `"npm"`, `"file"`, `"directory"`, `"hostPattern"`, `"pathPattern"` | Restricts plugin installation to explicitly listed marketplaces |
+| `telemetry` | `object` | `enabled` (`boolean`), `endpoint` (`string`), `protocol` (`"http/json"` or `"http/protobuf"`), `captureContent` (`boolean`), `lockCaptureContent` (`boolean`), `serviceName` (`string`), `resourceAttributes` (`object`), `headers` (`object`) | Configures OpenTelemetry export for {% data variables.product.prodname_vscode_shortname %} |
 
 {% endrowheaders %}
 
@@ -49,7 +44,8 @@ The following example shows these keys in one managed settings file.
 ```json
 {
   "permissions": {
-    "disableBypassPermissionsMode": "disable"
+    "disableBypassPermissionsMode": "disable",
+    "model": "auto"
   },
   "enabledPlugins": {
     "my-plugin@agent-skills": true
@@ -68,13 +64,10 @@ The following example shows these keys in one managed settings file.
       "repo": "OWNER/REPO"
     }
   ],
-  "model": {
-    "default": "MODEL-NAME"
-  },
   "telemetry": {
     "enabled": true,
     "endpoint": "https://otel-collector.example.com",
-    "protocol": "otlp-http",
+    "protocol": "http/protobuf",
     "captureContent": false,
     "lockCaptureContent": true,
     "serviceName": "copilot",
@@ -87,3 +80,62 @@ The following example shows these keys in one managed settings file.
   }
 }
 ```
+
+## `enabledPlugins`
+
+Defines plugins that are automatically installed or blocked for all enterprise users. Each entry uses the format `PLUGIN-NAME@MARKETPLACE-NAME` as the key, with a boolean value: `true` to require the plugin to be enabled, or `false` to require it to be disabled. See [AUTOTITLE](/copilot/concepts/agents/about-enterprise-plugin-standards).
+
+## `extraKnownMarketplaces`
+
+Defines additional plugin marketplaces available to users. Each entry is a named marketplace object containing a `source` property. The following source types are supported:
+
+* `"github"` — requires `repo` in `OWNER/REPO` format; optional `ref` (branch, tag, or SHA) and `path` (subdirectory)
+* `"git"` — requires `url`; optional `ref` and `path`
+* `"directory"` — requires `path`
+
+See [AUTOTITLE](/copilot/concepts/agents/about-enterprise-plugin-standards).
+
+## `strictKnownMarketplaces`
+
+Restricts plugin installation to only the marketplaces explicitly defined by the enterprise. An empty array means complete lockdown. Each entry is a marketplace object with a `source` property indicating the source type. The following source types are supported:
+
+* `"github"` — requires `repo` in `OWNER/REPO` format; optional `ref` and `path`
+* `"git"` — requires `url`; optional `ref` and `path`
+* `"url"` — requires `url`; optional `headers` object
+* `"npm"` — requires `package`
+* `"file"` — requires `path`
+* `"directory"` — requires `path`
+* `"hostPattern"` — requires `hostPattern` (regex matching marketplace hosts)
+* `"pathPattern"` — requires `pathPattern` (regex matching marketplace paths)
+
+## `permissions`
+
+### `disableBypassPermissionsMode`
+
+Prevents users from enabling bypass mode (also known as "YOLO mode") in {% data variables.copilot.copilot_cli_short %} and {% data variables.product.prodname_vscode_shortname %}. Bypass mode lets an agent run commands, access files, and fetch URLs without asking for approval.
+
+When you set `disableBypassPermissionsMode` to `"disable"`, users cannot turn on bypass mode in either client:
+
+* In {% data variables.copilot.copilot_cli_short %}, the `--yolo` and `--allow-all` command-line options and the `/yolo` and `/allow-all` slash commands are blocked. Individual flags such as `--allow-all-tools` and `--allow-all-paths` are not blocked.
+* In {% data variables.product.prodname_vscode_shortname %}, the global auto-approve setting (`chat.tools.global.autoApprove`), also known as "YOLO mode," is turned off and cannot be re-enabled.
+
+### `model`
+
+Sets auto model selection as the default for new conversations in {% data variables.copilot.copilot_cli_short %}. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection).
+
+When you set `permissions.model` to `"auto"`, new sessions use Auto model unless the user specifies a different model on a per-conversation basis.
+
+## `telemetry`
+
+Configures OpenTelemetry export, routing {% data variables.product.prodname_copilot_short %} usage data to a collector of your choice.
+
+When you set the `telemetry` property, {% data variables.product.prodname_copilot_short %} telemetry is sent to the endpoint you specify. The following sub-properties are supported:
+
+* `enabled`: Set to `true` to turn on telemetry export, or `false` to turn it off.
+* `endpoint`: The URL of your OTLP collector (for example, `https://otel-collector.example.com`).
+* `protocol`: The transport protocol for telemetry export. Accepted values are `"http/json"` and `"http/protobuf"`.
+* `captureContent`: Set to `true` to include prompt and response content in the telemetry payload, or `false` to exclude it.
+* `lockCaptureContent`: Set to `true` to prevent users from changing the `captureContent` setting.
+* `serviceName`: A label for the telemetry service name (for example, `"copilot"`).
+* `resourceAttributes`: An object of OpenTelemetry resource attributes to attach to all exported telemetry (for example, `{"deployment.environment": "production"}`).
+* `headers`: An object of HTTP headers to include with each telemetry request (for example, an `Authorization` header for your collector).

src/content-pipelines/config.yml

@@ -34,6 +34,7 @@ copilot-cli:
     All information relating to files in the ~/.copilot configuration directory, and settings in those files, should go in content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md.
     All reference details relating to hooks should go in content/copilot/reference/hooks-reference.md.
     All other CLI topics (MCP, skills, agents, permissions, etc.) belong in content/copilot/reference/copilot-cli-reference/cli-command-reference.md even when they mention plugins.
+    Do not overwrite the paragraph starting "OTel configuration can also be set in..." in cli-command-reference.md
 
 # TODO
 # mcp-server: