Bunch of docs changes to clarify Fleet enrollment

.vale/styles/config/vocabularies/Smallstep/accept.txt

@@ -952,4 +952,6 @@ publicKey
 serialNumber
 testuser
 disallow
+osquery
+fleetctl
 APNs

platform/enrollment-guide.mdx

@@ -1,5 +1,5 @@
 ---
-updated_at: February 03, 2026
+updated_at: September 8, 2026
 title: Device Enrollment Guide
 html_title: Device Enrollment Implementation Guide
 description: Step-by-step guide for device enrollment and inventory management. Set up secure certificate enrollment for all enterprise devices.
@@ -31,7 +31,7 @@ into your Smallstep inventory:
 You can [manually invite users
 to join your Smallstep team](https://smallstep.com/app/?next=/users/invite),
 and they will be able to self-enroll devices
-using the [Smallstep Agent](./smallstep-agent.mdx).
+using the [Smallstep Agent](./smallstep-agent.mdx)'s `step-agent register` subcommand.
 
 By default, administrators
 must approve a new device
@@ -69,25 +69,35 @@ until Smallstep receives an attestation from the device.
 For a concrete example,
 see [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx)
 
+### Use osquery-based enrollment
+
+For [Fleet-managed](../tutorials/connect-fleet-dm-to-smallstep.mdx) macOS, Linux, and Windows hosts, deploy the Smallstep osquery extension alongside the agent.
+The osquery extension reports each device's identity to Fleet:
+the TPM Endorsement Key on Linux and Windows,
+and the serial number and agent attestation key on macOS.
+Smallstep then syncs the data into your inventory.
+
 ### Add devices via API
 
 You can import devices from any source into Smallstep using our API.
 
+Use this when your devices are inventoried in a system that Smallstep can't sync from.
+
 Devices added via API are automatically approved.
 but they will not be marked as high-assurance
 until Smallstep receives an attestation from the device.
 
 You'll need [an API token](https://smallstep.com/app/?next=/settings/api/tokens/add) with all “device” scopes (put-device, patch-device, etc.).
 
-Use the [Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) endpoint to create a device.
+Use the [Add Device](https://gateway.smallstep.com/v2026-05-01/operations/PostDevices) endpoint to create a device.
 - For Apple devices, the `permanentIdentifier` must be the device's 9-character serial number.
 - For TPM 2.0 devices, the `permanentIdentifier` must be the TPM Endorsement Key URI, in the format `urn:ek:sha256:ul3sYf6uQ6jVEXAMPLEXoAuHI10U8gTvEJ6bMj95LXI=`. (You can retrieve the EK URI by running `step agent tpm --fingerprint` on the device.)
 - To create and assign a user to a device, fill in the `user` fields.
 
 Once added,
 the devices will be automatically approved.
 
-You can see the device using the [List Devices](https://gateway.smallstep.com/v2025-01-01/operations/ListDevices) endpoint:
+You can see the device using the [List Devices](https://gateway.smallstep.com/v2026-05-01/operations/ListDevices) endpoint:
 
 ```bash
 set +o history
@@ -96,7 +106,7 @@ set -o history
 curl -sH @api_headers --request GET \
   --url https://gateway.smallstep.com/api/devices \
   --header 'Accept: application/json' \
-  --header 'x-smallstep-api-version: 2025-01-01' | jq
+  --header 'x-smallstep-api-version: 2026-05-01' | jq
 ```
 
 You'll also see new devices in the Smallstep console,

platform/smallstep-agent.mdx

@@ -1,5 +1,5 @@
 ---
-updated_at: July 27, 2026
+updated_at: September 8, 2026
 title: Install the Smallstep Agent
 html_title: Install the Smallstep Agent on macOS, Windows, and Linux
 description: Install, configure, and deploy the Smallstep Agent on macOS, Windows, and Linux endpoints. Includes manual install, MDM integration, system requirements, and network endpoints.
@@ -22,6 +22,7 @@ Using an MDM? See:
 - [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx) (macOS)
 - [Connect Intune to Smallstep](../tutorials/connect-intune-to-smallstep.mdx) (Windows)
 - [Connect Workspace ONE to Smallstep](../tutorials/connect-workspace-one-to-smallstep.mdx) (Windows)
+- [Connect Fleet DM to Smallstep](../tutorials/connect-fleet-dm-to-smallstep.mdx)
 </Alert>
 
 Running into trouble? See the [Smallstep Agent troubleshooting guide](./troubleshooting-agent.mdx).
@@ -402,11 +403,11 @@ That is the `sha256-…` form Nix prints in its own messages, so a mismatch is e
 On `aarch64` hosts, use the `_linux_arm64.tar.gz` file and its hash.
 Then run `sudo nixos-rebuild switch` and confirm with `step-agent version`.
 
-## Registering and approving endpoints
+## Registering and approving NixOS endpoints
 
 ### Self-registration
 
-Users can configure the agent and register their Linux device with your Smallstep team by running:
+For a device that is not yet in your Smallstep inventory, users can configure the agent and register their Linux device with your Smallstep team by running:
 
 ```bash
 sudo step-agent register [team name]
@@ -417,7 +418,7 @@ Devices must be approved by an admin before they can be used.
 
 ### Pre-registration via API
 
-Alternatively, you can pre-register all of your team's devices:
+If your devices are inventoried in a system that Smallstep can't sync from, you can pre-register them via the API instead of having each device self-register:
 
 1. [Register and approve your devices via API](./enrollment-guide.mdx#add-devices-via-api).
    The devices you add via API will be pre-approved.
@@ -434,7 +435,6 @@ Alternatively, you can pre-register all of your team's devices:
        - Select the Smallstep Agents authority
        - Use the sha256 Root fingerprint displayed on this page
 
-
 ## Start the agent
 
 Finally, enable and start the agent:

platform/troubleshooting-agent.mdx

@@ -1,5 +1,5 @@
 ---
-updated_at: July 27, 2026
+updated_at: September 8, 2026
 title: Troubleshooting Guide
 html_title: Smallstep Troubleshooting Guide
 description: Troubleshoot Smallstep Device Identity issues. Diagnose platform, MDM, and endpoint problems with step-by-step guidance.
@@ -97,6 +97,15 @@ The agent may not be installed or may not be running on the device.
    - Try rebooting the device.
 4. If the agent still hasn't logged in, contact Smallstep support.
 
+**Symptom:** "`step-agent register` fails with `unprocessable entity`, or the browser prompts me to register a device that is already in my inventory"
+
+This happens when the device was synced from an MDM that reports its TPM Endorsement Key or was added via the API. `step-agent register` tries to create a second device entry, which conflicts with the existing one.
+
+**Troubleshooting steps:**
+1. Don't run `step-agent register` on the device. Write the agent configuration file directly and start the agent service. See [Pre-registration via API](./smallstep-agent.mdx#pre-registration-via-api).
+2. If a duplicate device was created, delete it in the [Smallstep console](https://smallstep.com/app/?next=/devices) and keep the entry that came from the MDM sync or the API.
+3. If the device shows as pending after the agent starts, approve it in the console.
+
 **Symptom:** "The device is approved, but it's not converting to a Smallstep-managed device (no green dot)"
 
 **Troubleshooting steps:**

tutorials/connect-fleet-dm-to-smallstep.mdx

@@ -1,5 +1,5 @@
 ---
-updated_at: May 21, 2026
+updated_at: September 8, 2026
 title: Connect Fleet DM to Smallstep
 html_title: Integrate Fleet DM with Smallstep Tutorial
 description: Connect Fleet DM with Smallstep for device security. Complete guide for deploying certificates and syncing device inventory using Fleet's device management platform.
@@ -289,10 +289,13 @@ Once the enrollment report is configured in Fleet, the Smallstep platform needs
 2. In the Smallstep console, edit your Fleet configuration
 3. Set the **Enrollment Query ID** to the numeric ID
 
+Your fleet's TPM information will begin syncing to Smallstep.
 
 ## Step 5. Linux agent configuration
 
-Linux does not support MDM configuration profiles, so the SCEP enrollment flow used for macOS and Windows does not apply. Instead, the Smallstep agent on Linux registers directly using TPM attestation. After installing the agent package and the osquery extension, you must configure the agent with your Smallstep team slug and CA fingerprint.
+Linux does not support MDM configuration profiles, so the SCEP enrollment flow used for macOS and Windows does not apply. Instead, the Smallstep agent on Linux uses ACME Device Attestation with the system's TPM.
+
+After installing the agent package and the osquery extension, you must configure the agent with your Smallstep team slug and CA fingerprint.
 
 When adding a Linux agent package in Fleet, add the following **post-install script** to configure and start the agent:
 
@@ -311,8 +314,34 @@ systemctl daemon-reload
 systemctl enable --now step-agent
 ```
 
+When the agent starts, it attests with the endpoint's TPM. Smallstep matches the attestation to the inventory data you just synced. By default, devices synced from Fleet need admin approval: if the host shows as `pending` in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there.
+
+To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` in your team's device enrollment policy. This setting isn't exposed in the Smallstep console. Use the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy) with an [API token](https://smallstep.com/app/?next=/settings/api/tokens/add) that has the `get-device-enrollment-policy` and `put-device-enrollment-policy` scopes. The `PUT` replaces the whole policy, so fetch the current policy first and resubmit it with `Fleet` added to `autoApproveSources`:
 
-After deployment, Linux devices will self-register with your Smallstep team via TPM attestation. By default, new devices require admin approval in the [Smallstep console](https://smallstep.com/app/?next=/devices). To automate approval, you can [pre-register devices via API](../platform/smallstep-agent.mdx#pre-registration-via-api).
+```bash
+set +o history
+echo "Authorization: Bearer [your API token]" > api_headers
+set -o history
+
+# Fetch the current policy
+curl -sH @api_headers --request GET \
+  --url https://gateway.smallstep.com/api/device-enrollment-policy \
+  --header 'Accept: application/json' \
+  --header 'x-smallstep-api-version: 2026-05-01' | jq
+
+# Resubmit it with Fleet in autoApproveSources.
+# Adjust both lists to match the policy you fetched.
+curl -sH @api_headers --request PUT \
+  --url https://gateway.smallstep.com/api/device-enrollment-policy \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header 'x-smallstep-api-version: 2026-05-01' \
+  --data '{
+    "allowedSources": ["Smallstep API", "Smallstep Agent", "Fleet"],
+    "autoApproveSources": ["Fleet"],
+    "requireUserBinding": true
+  }' | jq
+```
 
 ## Step 6. Confirmation (Linux)
 
@@ -444,7 +473,34 @@ Add the Smallstep agent MSI as Fleet software so it installs on enrollment:
 2. In the Fleet console, go to **Software**, choose **Add software → Custom package**, and upload the MSI
 3. Scope the install to your Windows hosts
 
-The agent reads the registry values written in Step 3 on startup, and completes TPM-attested registration with your Smallstep team.
+On startup, the agent reads the registry values to find the team information, then attests with the endpoint's TPM. Smallstep matches the attestation to the inventory data synced from Fleet.
+
+By default, devices synced from Fleet need admin approval: if the host shows as pending in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` in your team's device enrollment policy. This setting isn't exposed in the Smallstep console. Use the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy) with an [API token](https://smallstep.com/app/?next=/settings/api/tokens/add) that has the `get-device-enrollment-policy` and `put-device-enrollment-policy` scopes. The `PUT` replaces the whole policy, so fetch the current policy first and resubmit it with `Fleet` added to `autoApproveSources`:
+
+```bash
+set +o history
+echo "Authorization: Bearer [your API token]" > api_headers
+set -o history
+
+# Fetch the current policy
+curl -sH @api_headers --request GET \
+  --url https://gateway.smallstep.com/api/device-enrollment-policy \
+  --header 'Accept: application/json' \
+  --header 'x-smallstep-api-version: 2026-05-01' | jq
+
+# Resubmit it with Fleet in autoApproveSources.
+# Adjust both lists to match the policy you fetched.
+curl -sH @api_headers --request PUT \
+  --url https://gateway.smallstep.com/api/device-enrollment-policy \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header 'x-smallstep-api-version: 2026-05-01' \
+  --data '{
+    "allowedSources": ["Smallstep API", "Smallstep Agent", "Fleet"],
+    "autoApproveSources": ["Fleet"],
+    "requireUserBinding": true
+  }' | jq
+```
 
 ## Step 6. Confirmation (Windows)