docs: Add paths: glob pattern support to GitOps YAML reference (#43600)

The glob/ `paths:` feature was added across PRs #40799 (scripts,
configuration_profiles) and #41141 (labels, policies, reports) but the
customer-facing YAML reference at `docs/Configuration/yaml-files.md` was
never updated to document it.

This adds documentation for:
- New `path:` vs `paths:` reference section explaining the difference
between singular (literal file) and plural (glob pattern)
- Characters to avoid in filenames when using `path:` (`*`, `?`, `[`,
`{`)
- `scripts` section: `paths:` support with `.sh`/`.ps1` filter note
- `apple_settings`/`windows_settings` section: `path:` vs `paths:` wit
examples
- `android_settings` section: `paths:` support note
- `labels`, `policies`, `reports` sections: `paths:` support notes
- `paths:` glob examples added to the controls YAML example for both
scripts, apple_settings, and windows_settings

Discovered via customer-sonet whose Windows profile filenames use
brackets as a CSP naming convention (e.g.
`[AllowSpotlightCollection].xml`), which are rejected by `path:`
validation as glob metacharacters.

See related bug report for the false positive on literal filenames.
https://github.com/fleetdm/fleet/issues/43598

<!-- Add the related story/sub-task/bug number, like Resolves #123, or
remove if NA -->
**Related issue:** Resolves #43598

Co-authored-by: Rachael Shaw <r@rachael.wtf>

docs/Configuration/yaml-files.md

@@ -33,12 +33,25 @@ package_path: package_name.yml
 package_path: ../software/package_name.yml
 ```
 
+### `path:` vs `paths:` (glob patterns)
+
+Several sections support both `path:` (singular) and `paths:` (plural), including `scripts`, `configuration_profiles`, `labels`, `policies`, and `reports`:
+
+- **`path:`** references a single, literal file path. Must not contain the characters `*`, `?`, `[`, or `{`.
+- **`paths:`** accepts a glob pattern to match multiple files at once (e.g. `../lib/windows/profiles/*.xml`).
+
+You cannot specify both `path:` and `paths:` on the same entry.
+
+> **Important:** Filenames containing `*`, `?`, `[`, or `{` cannot be referenced using `path:`. If your filenames contain these characters (e.g. Windows profiles named `[AllowSpotlightCollection].xml`), either rename the files to remove them, or use `paths:` with a wildcard pattern like `*.xml`.
+
 For the GitOps API token, create a dedicated API-only user with `fleetctl user create --api-only`. These users can modify configurations via GitOps but can’t access the Fleet UI. Assign the GitOps role and set the appropriate global or fleet scope in the UI.
 
 ## labels
 
 Labels can be specified in your `default.yml` and `fleets/fleet-name.yml` files using inline configuration or references to separate files in your `lib/` folder. Labels cannot be specified in `fleets/unassigned.yml`.
 
+Labels support `path:` (single file) and `paths:` (glob pattern) references. See [`path:` vs `paths:`](#path-vs-paths-glob-patterns) for details. Filenames must not contain `*`, `?`, `[`, or `{` when using `path:`.
+
 - `name` specifies the label's name. Must be unique across all global and fleet labels.
     + Changing a label's `name` in GitOps will delete and re-create the label, temporarily clearing its membership. To avoid this, update the label name in the UI before making the change in YAML. 
 - `description` specifies the label's description.
@@ -119,6 +132,8 @@ labels:
 
 Policies can be specified inline in your `default.yml`, `fleets/fleet-name.yml`, or `fleets/unassigned.yml` files. They can also be specified in separate files in your `lib/` folder.
 
+Policies support `path:` (single file) and `paths:` (glob pattern) references. See [`path:` vs `paths:`](#path-vs-paths-glob-patterns) for details. Filenames must not contain `*`, `?`, `[`, or `{` when using `path:`.
+
 ### Options
 
 For available options, see the parameters for the [Create policy](https://fleetdm.com/docs/rest-api/rest-api#create-policy) and [Create team policy](https://fleetdm.com/docs/rest-api/rest-api#create-team-policy) API endpoints.
@@ -236,6 +251,8 @@ policies:
 
 Reports can be specified inline in your `default.yml` file or `fleets/fleet-name.yml` files. They can also be specified in separate files in your `lib/` folder.
 
+Reports support `path:` (single file) and `paths:` (glob pattern) references. See [`path:` vs `paths:`](#path-vs-paths-glob-patterns) for details. Filenames must not contain `*`, `?`, `[`, or `{` when using `path:`.
+
 ### Options
 
 For possible options, see the parameters for the [Create report API endpoint](https://fleetdm.com/docs/rest-api/rest-api#create-report).
@@ -354,7 +371,7 @@ agent_options:
 
 The `controls` section allows you to configure scripts and device management (MDM) features in Fleet.
 
-- `scripts` is a list of paths to macOS, Windows, or Linux scripts.
+- `scripts` is a list of paths to macOS, Windows, or Linux scripts. Supports `path:` (single file) and `paths:` (glob pattern, filtered to `.sh` and `.ps1` files only). Filenames must not contain `*`, `?`, `[`, or `{` when using `path:`. See [`path:` vs `paths:`](#path-vs-paths-glob-patterns) for details.
 - `windows_enabled_and_configured` specifies whether or not to turn on Windows MDM features (default: `false`). Can only be configured for "All fleets" (`default.yml`).
 - `windows_entra_tenant_ids` is a list of Microsoft Entra tenant IDs to enable automatic (Autopilot) and manual enrollment by end users (**Settings** > **Accounts** > **Access work or school** on Windows). Can only be configured for "All fleets" (`default.yml`). Find your **Tenant ID**, on [**Microsoft Entra ID** > **Home**](https://entra.microsoft.com/#home).
 - `enable_turn_on_windows_mdm_manually` specifies whether or not to require end users to manually turn on MDM in **Settings > Access work or school** (default: `false`). If `false`, MDM is automatically turned on for all Windows hosts that aren't connected to any MDM solution. Can only be configured for "All fleets" (`default.yml`).
@@ -371,6 +388,7 @@ controls:
     - path: ../lib/macos-script.sh
     - path: ../lib/windows-script.ps1
     - path: ../lib/linux-script.sh
+    - paths: ../lib/scripts/*.sh  # Glob pattern (filtered to .sh and .ps1 only)
   windows_enabled_and_configured: true
   windows_entra_tenant_ids:
     - 4e342a0d-ec1a-4353-bdeb-785542e0a8fb
@@ -396,7 +414,14 @@ controls:
       - path: ../lib/macos-profile1.mobileconfig
         labels_exclude_any: # Available in Fleet Premium
           - Macs on Sequoia
+<<<<<<< AdamBaali-Gitops-YAML-globs-update
+      - path: ../lib/macos-profile2.json
+        labels_include_all: # Available in Fleet Premium
+          - Macs on Sonoma
+      - paths: ../lib/macos/profiles/*.mobileconfig  # Glob pattern to include all .mobileconfig files
+=======
       - path: ../lib/macos-profile3.mobileconfig
+>>>>>>> main
         labels_include_any: # Available in Fleet Premium
           - Engineering
           - Product
@@ -404,6 +429,9 @@ controls:
   windows_settings:
     configuration_profiles:
       - path: ../lib/windows-profile.xml
+      - paths: ../lib/windows/profiles/*.xml  # Glob pattern to include all .xml files in directory
+        labels_include_any:
+          - Engineering
   android_settings:
     configuration_profiles:
       - path: ../lib/android-profile.json
@@ -446,14 +474,21 @@ controls:
 
 ### apple_settings and windows_settings
 
-- `apple_settings.configuration_profiles` is a list of paths to macOS, iOS, and iPadOS configuration profiles (.mobileconfig) or declaration profiles (.json).
-- `windows_settings.configuration_profiles` is a list of paths to Windows configuration profiles (.xml).
+- `apple_settings.configuration_profiles` is a list of macOS, iOS, and iPadOS configuration profiles (.mobileconfig) or declaration profiles (.json).
+- `windows_settings.configuration_profiles` is a list of Windows configuration profiles (.xml).
+
+Each entry can use either `path:` or `paths:`:
+
+- **`path:`** references a single file. Filenames must not contain `*`, `?`, `[`, or `{`.
+- **`paths:`** accepts a [glob pattern](#path-vs-paths-glob-patterns) to match multiple files (e.g. `../lib/windows/profiles/*.xml`). Labels and other options specified on a `paths:` entry apply to all matched files.
 
 Use `labels_include_all` to target hosts that have all labels, `labels_include_any` to target hosts that have any label, or `labels_exclude_any` to target hosts that don't have any of the labels. Only one of `labels_include_all`, `labels_include_any`, or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted.
 
 ### android_settings
 
-- `android_settings.configuration_profiles` is a list of paths to Android configuration profiles (.json).
+- `android_settings.configuration_profiles` is a list of Android configuration profiles (.json).
+
+Each entry can use either `path:` or `paths:`. Filenames must not contain `*`, `?`, `[`, or `{` when using `path:`. See [`path:` vs `paths:`](#path-vs-paths-glob-patterns) for glob pattern support.
 
 Use `labels_include_all` to target hosts that have all labels, `labels_include_any` to target hosts that have any label, or `labels_exclude_any` to target hosts that don't have any of the labels. Only one of `labels_include_all`, `labels_include_any`, or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted.