Consolidate install instructions into smallstep-agent page (EFF-313)

manifest.json

@@ -78,11 +78,7 @@
           "title": "Configure Devices for Smallstep",
           "routes": [
             {
-              "title": "Install the Smallstep App",
-              "path": "/platform/smallstep-app.mdx"
-            },
-            {
-              "title": "Deploy the Agent",
+              "title": "Install the Smallstep Agent",
               "path": "/platform/smallstep-agent.mdx"
             },
             {

platform/enrollment-guide.mdx

@@ -31,8 +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 Desktop App](./smallstep-app.mdx)
-or the [Smallstep Agent](./smallstep-agent.mdx).
+using the [Smallstep Agent](./smallstep-agent.mdx).
 
 By default, administrators
 must approve a new device
@@ -48,8 +47,7 @@ With IdP self-enrollment enabled,
 when you connect Smallstep to your identity provider,
 your users will be able to self-enroll
 via single sign-on,
-using the [Smallstep Desktop App](./smallstep-app.mdx)
-or the [Smallstep Agent](./smallstep-agent.mdx).
+using the [Smallstep Agent](./smallstep-agent.mdx).
 
 By default, administrators
 must approve newly enrolled devices

platform/smallstep-agent.mdx

@@ -1,55 +1,116 @@
 ---
-updated_at: February 03, 2026
-title: Deploy the Agent
-html_title: Deploy the Smallstep Agent
-description: Distribute and configure Smallstep Agent on Linux, macOS, and Windows. For organizations without MDM or using script-based deployment.
+updated_at: May 21, 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.
 ---
 
-The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints.
+The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints across macOS, Windows, and Linux.
+
+The agent runs as a background service on all platforms. Smallstep also has an optional desktop UI for transparency and troubleshooting, offered as a separate package.
 
 # Introduction
 
-This guide covers **manual installation** of the Smallstep Agent on:
+This guide covers installation of the Smallstep Agent on:
 
 * [Linux](#linux-installation)
 * [macOS](#macos-installation)
 * [Windows](#windows-installation)
 
-Use this guide if you
-want to install the agent
-via a software management tool separate from your MDM (eg Ansible, Munki),
-or if your MDM only supports limited software management workflows.
-
 <Alert severity="info">
 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)
 </Alert>
 
-# Network access
+Running into trouble? See the [Smallstep Agent troubleshooting guide](./troubleshooting-agent.mdx).
 
-The agent will connect to the following Smallstep hosts:
-- Your CA: `<your-team>.ca.smallstep.com` and subdomains
-- Agent API: `control.infra.smallstep.com`
-- Smallstep API: `gateway.smallstep.com`
-- TPM Attestation CA: `att.smallstep.com`
+# System requirements
 
-# Linux installation
+## Windows
 
-## System requirements
+- Windows 10 or later (Windows Home editions are _not_ supported)
+- Trusted Platform Module (TPM 2.0)
+- Architectures: `amd64`, `arm64`
+
+## macOS
+
+- macOS 13 (Ventura) or later
+- Secure Enclave
+- The agent must be installed for a single user (multi-user deployments are not yet supported)
+
+## Linux
 
 - Supported operating systems:
     - Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc)
     - Ubuntu (Current Stable and LTS)
     - Debian (Current Releases)
     - Fedora (Current Releases)
+- `systemd`-based service manager
 - A TPM 2.0 module is required. Smallstep depends on TPMs to create a high-assurance device inventory.
-- We support `amd64` and `arm64` architectures
-- The following directories are used by default:
-    - runtime state in `/run/step-agent`
-    - configuration in `/etc/step-agent`
-    - certificates in `/var/lib/step-agent` and in your configured locations
+- `p11-kit`, `tpm-tss2`
+- Architectures: `amd64`, `arm64`
+
+# Runtime requirements
+
+All platforms require an internet connection for normal operation.
+
+## Windows
+
+- *Administrator privileges* — the Smallstep Agent requires privilege escalation to be able to communicate with the TPM.
+
+## macOS
+
+- *Location permission* — only required if the agent will manage Wi-Fi network configurations.
+- *Keychain access* — the agent uses the macOS keychain to store both keys and certificates it manages.
+- *Network Extension entitlement* — the Smallstep Agent requests the *Network Extension* entitlement so that it can manage VPN connections.
+
+## Linux
+
+- *TPM read/write permission* — the Smallstep Agent communicates to the TPM from user-space using `tpm-tss2`, and the running user must have read/write permissions to the TPM resource manager (typically `/dev/tpmrm0`).
+
+# Connectivity requirements
+
+The agent connects to the following Smallstep hosts:
+
+- Your CA: `<your-team>.ca.smallstep.com` and subdomains
+- Agent API: `control.infra.smallstep.com`
+- Smallstep API: `gateway.smallstep.com`
+- TPM Attestation CA: `att.smallstep.com`
+
+# Downloads
+
+## All versions
+
+See [releases.smallstep.com](https://releases.smallstep.com) for all release history of 
+the Smallstep Agent, Smallstep Desktop app, and more.
+
+## Latest stable agent packages
+
+Here are URLs that always point at the latest stable release of the agent:
+
+**macOS**
+
+- [step-agent_latest.pkg](https://packages.smallstep.com/stable/darwin/step-agent_latest.pkg)
+
+**Windows**
+
+- [step-agent_amd64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_amd64_latest.msi)
+- [step-agent_arm64_latest.msi](https://packages.smallstep.com/stable/windows/step-agent_arm64_latest.msi)
+
+**Linux**
+
+- [step-agent_amd64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.deb)
+- [step-agent_arm64_latest.deb](https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.deb)
+- [step-agent_x86_64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_x86_64_latest.rpm)
+- [step-agent_aarch64_latest.rpm](https://packages.smallstep.com/stable/linux/step-agent_aarch64_latest.rpm)
+- [step-agent_amd64_latest.pkg.tar.zst](https://packages.smallstep.com/stable/linux/step-agent_amd64_latest.pkg.tar.zst)
+- [step-agent_arm64_latest.pkg.tar.zst](https://packages.smallstep.com/stable/linux/step-agent_arm64_latest.pkg.tar.zst)
+
+# Linux installation
+
+Smallstep also offers Debian and RPM package repositories.
 
 ## Quick install
 
@@ -292,18 +353,7 @@ In Chrome, you should now have access to certificates managed by Smallstep.
 
 For regular usage, add `P11_KIT_SERVER_ADDRESS` to your environment more permanently. For example, you might add `P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock`  to your global `/etc/environment` file.
 
-#### Troubleshooting
-
-The agent produces a log file or journal entries in systemd, depending on how it is installed and run.
-
-You can use tools like `pkcs11-tool` for troubleshooting PKCS#11 support:
-
-```bash
-pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so \
-         --list-slots
-```
-
-See the [p11-kit](https://p11-glue.github.io/p11-glue/p11-kit/manual/) documentation for more details.
+If PKCS#11 isn't working as expected, see [PKCS#11 troubleshooting](./troubleshooting-agent.mdx#pkcs11-not-working-linuxmacos).
 
 ## Uninstall
 
@@ -329,12 +379,6 @@ To uninstall the Smallstep Agent from a Linux system:
 
 # macOS installation
 
-## System requirements
-
-- macOS 10.15 (Catalina) or later
-- The agent must be installed for a single user (multi-user deployments are not yet supported)
-- Installation location: `/Applications/SmallstepAgent.app`
-
 ## Manual install
 
 1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent_latest.pkg)
@@ -373,13 +417,13 @@ To uninstall the Smallstep Agent from a macOS system:
 
    Replace `<team-id>` with your Team ID from the Smallstep UI (found in [Settings → Team](https://smallstep.com/app/?next=/settings/team)).
 
-3. Remove the application directory:
+2. Remove the application directory:
 
    ```bash
    rm -rf /Applications/SmallstepAgent.app
    ```
 
-4. Remove the package receipt:
+3. Remove the package receipt:
 
    ```bash
    if pkgutil --packages | grep -q com.smallstep.Agent; then
@@ -389,13 +433,6 @@ To uninstall the Smallstep Agent from a macOS system:
 
 # Windows installation
 
-## System requirements
-
-- Windows 10 (Anniversary Edition) or later
-- Windows Home is not supported
-- A TPM 2.0 module is required
-- We support `amd64` and `arm64` architectures
-
 ## Install via Winget
 
 Install the agent via [Winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/):

platform/troubleshooting-agent.mdx

@@ -127,9 +127,9 @@ This section covers issues with individual devices, the Smallstep Agent, and end
 ### Prerequisites
 
 Before troubleshooting endpoint issues, verify the device meets requirements:
-- Review [System Requirements](./smallstep-app.mdx#system-requirements)
-- Check [Runtime Requirements](./smallstep-app.mdx#runtime-requirements)
-- Verify [Connectivity Requirements](./smallstep-app.mdx#connectivity-requirements)
+- Review [System Requirements](./smallstep-agent.mdx#system-requirements)
+- Check [Runtime Requirements](./smallstep-agent.mdx#runtime-requirements)
+- Verify [Connectivity Requirements](./smallstep-agent.mdx#connectivity-requirements)
 
 ### Using the doctor command
 
@@ -417,7 +417,7 @@ This outputs check results in JSON format:
 **Solutions:**
 1. Verify internet connectivity: `ping 8.8.8.8`
 2. Test DNS resolution: `nslookup gateway.smallstep.com`
-3. Review [Connectivity Requirements](./smallstep-app.mdx#connectivity-requirements)
+3. Review [Connectivity Requirements](./smallstep-agent.mdx#connectivity-requirements)
 4. Check corporate firewall and proxy settings
 5. Ensure all required Smallstep hosts are allowlisted
 
@@ -462,6 +462,19 @@ This outputs check results in JSON format:
 - Chrome/Firefox don't see Smallstep certificates
 - NetworkManager can't use agent certificates
 
+**Diagnose:**
+
+The agent produces a log file or journal entries in systemd, depending on how it is installed and run. Start there.
+
+You can also use tools like `pkcs11-tool` to enumerate the slots exposed by the PKCS#11 server:
+
+```bash
+pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so \
+         --list-slots
+```
+
+The location of `p11-kit-client.so` may vary by distribution.
+
 **Solutions:**
 1. Verify PKCS#11 socket exists and is accessible
 2. Set environment variable correctly:
@@ -471,6 +484,7 @@ This outputs check results in JSON format:
 3. Install p11-kit if not present
 4. Test with `pkcs11-tool --list-slots`
 5. See [PKCS#11 configuration guide](./smallstep-agent.mdx#openssl-and-pkcs11-support)
+6. See the [p11-kit documentation](https://p11-glue.github.io/p11-glue/p11-kit/manual/) for general PKCS#11 reference
 
 #### Cannot access a resource (wi-fi, VPN, web app)