Refactor documentation for clarity and consistency

- Updated sidebar links to correct paths, ensuring accurate navigation to Kubernetes deployment references.
- Standardized formatting across multiple files, including titles and descriptions, for improved readability.
- Enhanced documentation by correcting typos and ensuring consistent terminology, particularly in the context of device identity and Kubernetes configurations.
- Consolidated and improved the organization of documentation related to Pomerium's capabilities and integrations, including the introduction of new sections for WebAuthn device identity.

These changes enhance the overall usability and clarity of the documentation, ensuring users have access to a more coherent and organized resource for managing Pomerium.

Author: desimone

.pre-commit-config.yaml

@@ -6,7 +6,7 @@ repos:
         additional_dependencies:
           - '[email protected]'
         files: ^content\/.*$
-        exclude: content/docs/deploy/k8s//reference.md
+        exclude: content/docs/deploy/k8s/reference.md
   - repo: https://github.com/streetsidesoftware/cspell-cli
     rev: v6.2.0
     hooks:

content/docs/capabilities/audit-logs.mdx

@@ -2,7 +2,7 @@
 title: Auditing & Privelege Access Management
 description: Learn how to read Pomerium authorization logs.
 lang: en-US
-sidebar_label: 'Audit logs'
+sidebar_label: 'Audit logging'
 keywords: [pomerium, troubleshooting, auth, authorization, logs]
 sidebar_class_name: enterprise
 ---

content/docs/capabilities/authorization.mdx

@@ -21,7 +21,14 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import SelfSignedCertWarning from '@site/content/docs/admonitions/_handle-self-signed-certificate-warning.mdx';
 
-# Pomerium's Authorization and Policy Enforcement
+<iframe
+  width="100%"
+  height="600"
+  src="https://www.youtube.com/embed/3MJrNvQ7aIE"
+  title="Pomerium authorization video"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  allowfullscreen></iframe>
 
 Pomerium enforces dynamic, context-aware authorization on every request. This capability extends across deployments of any size or complexity, from single-route use cases to multi-namespace or multi-cluster enterprise environments.
 
@@ -35,15 +42,6 @@ Pomerium's approach to authorization is continuous and context-aware, integratin
 - **Namespace-based** and **cluster-based** organization in Enterprise and Zero
 - **Policy languages**: [PPL](#pomerium-policy-language-ppl) for most use cases, [Rego](#rego-policies) for advanced logic
 
-<iframe
-  width="100%"
-  height="600"
-  src="https://www.youtube.com/embed/3MJrNvQ7aIE"
-  title="Pomerium authorization video"
-  frameborder="0"
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-  allowfullscreen></iframe>
-
 ## Where Policies Live
 
 1. **Routes**  

content/docs/capabilities/getting-users-identity.mdx

@@ -3,7 +3,7 @@
 
 title: Identity & Context Verification with JWTs
 description: Learn how Pomerium uses JWTs for identity and context verification, how it fits into a zero trust environment, and four ways to validate the JWT in your upstream service.
-sidebar_label: Identity & Context Verification
+sidebar_label: Continious Identity Verification
 keywords:
   - jwt
   - jwt authentication
@@ -28,6 +28,15 @@ import ExpressApp from '/content/examples/js-sdk/express-server.md';
 
 # Identity & Context Verification with JWT
 
+<iframe
+  width="100%"
+  height="600"
+  src="https://www.youtube.com/embed/mc9USXDiCmk"
+  title="YouTube video player"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  allowfullscreen></iframe>
+
 Pomerium uses JSON Web Tokens (JWTs) to help your upstream services verify a user's identity and additional context (like group membership) at the **application layer**. In a zero trust environment, verifying that **both** the client and server are who they say they are is crucial. Pomerium handles user authentication, then mints a **signed JWT** for every verified and authorized request.
 
 By validating that JWT, your application or service confirms:
@@ -43,15 +52,6 @@ This article explains **why** identity & context verification at the application
 3. **Custom application** (using an existing JWT library or Pomerium's SDK)
 4. **Sidecar** (no code changes, e.g. Envoy proxy)
 
-<iframe
-  width="100%"
-  height="415"
-  src="https://www.youtube.com/embed/mc9USXDiCmk"
-  title="YouTube video player"
-  frameborder="0"
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-  allowfullscreen></iframe>
-
 ## JWT Authentication Flow
 
 ![A diagram that shows how Pomerium forwards JWTs to an upstream application](./img/jwt-authn/jwt-authentication.svg)

content/docs/capabilities/routing.mdx

@@ -1,7 +1,7 @@
 ---
 # cSpell:ignore cm9vdDpodW50ZXI0Mg
 
-title: Routing, Proxying, and Load Balancing
+title: Routing, Proxying, and Load Balancing with Pomerium
 lang: en-US
 sidebar_label: 'Proxying & Routing'
 description: How to get Pomerium's CLI which be used to proxy TCP services and kubernetes commands
@@ -20,19 +20,17 @@ keywords:
   ]
 ---
 
-# Routing, Proxying, and Load Balancing
-
-## Routes
-
 <iframe
   width="100%"
-  height="500"
+  height="600"
   src="https://www.youtube.com/embed/-wAKnj_cY-E"
   frameborder="0"
   webkitallowfullscreen="true"
   mozallowfullscreen="true"
   allowfullscreen="true"></iframe>
 
+## Routing
+
 A **Route** defines how to access a service running behind Pomerium. This includes authentication (both for Pomerium and passed through to the service), rewrites, header management, load balancing, etc.
 
 When first installing Pomerium Enterprise, users may want to import existing routes from the open-source Pomerium core. The **Migrate Routes** button accepts the open-source `config.yaml` file and imports routes from it to Pomerium Enterprise.

content/docs/deploy/enterprise/install.mdx

@@ -207,7 +207,7 @@ kubectl apply -k ./config
 
 ```
 
-[pomerium kustomize]: /docs/deploy/k8s//install
+[pomerium kustomize]: /docs/deploy/k8s/install
 [environment variables]: /docs/deploy/enterprise/configure
 [ingress]: /docs/deploy/k8s/ingress
 

content/docs/deploy/k8s/configure.md

@@ -48,7 +48,7 @@ Integration with your Identity Provider is configured using [`identityProvider`]
 
 ### Authenticate endpoint
 
-Each Pomerium installation has a special route that unauthenticated users are redirected to that handles sign-in via your Identity Provider. It is configured via the [`authenticate`](/docs/deploy/k8s//reference#authenticate) parameter of the [CRD](./reference#authenticate).
+Each Pomerium installation has a special route that unauthenticated users are redirected to that handles sign-in via your Identity Provider. It is configured via the [`authenticate`](/docs/deploy/k8s/reference#authenticate) parameter of the [CRD](./reference#authenticate).
 
 The authenticate endpoint DNS address should resolve to an external IP address assigned by your Kubernetes Load Balancer to the `pomerium-proxy` service. If you use `external-dns`, that may be [done automatically](#external-dns).
 

content/docs/deploy/k8s/gateway-api.mdx

@@ -74,7 +74,7 @@ To install the Pomerium Ingress Controller with support for Gateway API:
 
    This installs and configures the Ingress Controller, and adds a [GatewayClass](https://gateway-api.sigs.k8s.io/concepts/api-overview/#gatewayclass) named `pomerium-gateway` for use with the Gateway API.
 
-1. You will also need to set up a [global Pomerium configuration](/docs/deploy/k8s//configure). This is a minimal example for use with Gateway API:
+1. You will also need to set up a [global Pomerium configuration](/docs/deploy/k8s/configure). This is a minimal example for use with Gateway API:
 
    ```yaml title="pomerium-global.yaml"
    apiVersion: ingress.pomerium.io/v1

content/docs/deploy/k8s/ingress.md

@@ -29,12 +29,12 @@ This document shows you how to configure an Ingress resource that's compatible w
 
 **Before you start:**
 
-This document assumes you've installed the Pomerium Ingress Controller and added global configuration settings with the [Pomerium CRD](/docs/deploy/k8s//configure).
+This document assumes you've installed the Pomerium Ingress Controller and added global configuration settings with the [Pomerium CRD](/docs/deploy/k8s/configure).
 
 If you haven't completed these steps, see the following docs:
 
-- [Install Pomerium Ingress Controller](/docs/deploy/k8s//install)
-- [Global Configuration](/docs/deploy/k8s//configure)
+- [Install Pomerium Ingress Controller](/docs/deploy/k8s/install)
+- [Global Configuration](/docs/deploy/k8s/configure)
 
 ## Configure an Ingress resource
 
@@ -87,7 +87,7 @@ spec:
 
 The default installation adds `pomerium` [IngressClass](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class) to your cluster. In order for Pomerium to service your Ingress objects, please set `spec.ingressClassName` to `pomerium`.
 
-It is also possible to [set Pomerium to be a default ingress controller](/docs/deploy/k8s//install#set-pomerium-as-default-ingressclass) cluster-wide.
+It is also possible to [set Pomerium to be a default ingress controller](/docs/deploy/k8s/install#set-pomerium-as-default-ingressclass) cluster-wide.
 
 ### Set Ingress annotations
 
@@ -544,7 +544,7 @@ spec:
 
 ## Metrics
 
-Pomerium [exposes](/docs/deploy/k8s//install#metrics) a number of Prometheus style metrics that you may use to monitor your Ingress.
+Pomerium [exposes](/docs/deploy/k8s/install#metrics) a number of Prometheus style metrics that you may use to monitor your Ingress.
 
 In order to filter out metrics for a particular Ingress, use `envoy_cluster_name` metric label, that has a `ingressnamespace-ingressname-host-domain-com` format.
 

content/docs/guides/cockpit.md

@@ -25,7 +25,7 @@ This guide assumes you already have Pomerium installed and connected to your [Id
 - Install Pomerium
   - [Binaries](/docs/core) if installing Pomerium as a system-level service.
   - [Pomerium using Docker](/docs/get-started/quickstart) if installing Pomerium as a Docker container
-  - [Install Pomerium using Kubernetes](/docs/deploy/k8s//quickstart) for Kubernetes environments.
+  - [Install Pomerium using Kubernetes](/docs/deploy/k8s/quickstart) for Kubernetes environments.
 - Connect to an IdP - See [Identity Provider Configuration](/docs/identity-providers) and find the article for your identity provider.
 
 ## Install & Configure Cockpit

content/docs/guides/helm.mdx

@@ -25,7 +25,7 @@ This guide will show you how to deploy Pomerium with [Helm] on [Kubernetes].
 
 :::warning
 
-After re-evaluating the complexity required to both use and manage Helm for Pomerium, we've opted not to continue updating our Helm chart. Instead we've created a simpler deployment method, which you can read about on our [Kubernetes Quickstart](/docs/deploy/k8s//quickstart) page.
+After re-evaluating the complexity required to both use and manage Helm for Pomerium, we've opted not to continue updating our Helm chart. Instead we've created a simpler deployment method, which you can read about on our [Kubernetes Quickstart](/docs/deploy/k8s/quickstart) page.
 
 :::
 

content/docs/guides/istio.mdx

@@ -112,7 +112,7 @@ Follow [Install Pomerium using Helm] to set up the Pomerium Ingress Controller a
        headless: false # send traffic to the Pomerium Databroker through the Istio service rather than to individual pods
    ```
 
-1. When [defining a test service](/docs/deploy/k8s//quickstart#test-service), you should now see two containers for the service pod:
+1. When [defining a test service](/docs/deploy/k8s/quickstart#test-service), you should now see two containers for the service pod:
 
    ```shell-session
    $ kubectl get pods

content/docs/integrations/device-context/device-identity.mdx

@@ -67,139 +67,6 @@ The nature of cross-platform keys mean they are not associated with a single end
 
 Device identity is the unique ID associated with a device. In the context of zero trust, device identity can be used to authenticate and authorize users and to determine if a device can be trusted before granting a user access to a protected application or service.
 
-<iframe
-  width="100%"
-  height="500"
-  src="https://www.youtube.com/embed/aJzgnaXEpLo?rel=0"
-  frameBorder="0"
-  allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-  allowFullScreen
-/>
-
-## Device identity with Pomerium
-
-Pomerium versions [0.16.0](/docs/core/upgrading#policy-for-device-identity) and up support the use of device identity as a criteria in authorization policies. Pomerium uses the [Web Authentication](https://www.w3.org/TR/webauthn-2/#registration-extension) (WebAuthn) API to bring authentication and authorization based on device identity into your security framework. With Pomerium's device identity support, users can register devices and administrators can limit access to devices they trust.
-
-## Device identity features
-
-Pomerium Enterprise and Core both support device identity, but Enterprise users can enroll and manage devices in the Enterprise Console.
-
-| Features (Enterprise) | Device Identity |
-| --- | :-: |
-| **Pre-approved device enrollment** | Administrators can enroll a new device and generate a registration link for a specific user. |
-| **Device management** | Administrators can view and manage approved and pending devices in the Enterprise Console. |
-| **User-initiated device enrollment** | Users can register their device if a route requires device identity authentication, but can only access the route if their device is approved in the Enterprise Console. |
-| **Features (Core)** | **Device Identity** |
-| **User-initiated device enrollment** | Users can register their device if a route requires device identity authentication and access the route without device approval. |
-
-## New enrollment (Enterprise)
-
-Device identity with Pomerium relies on a [trust on first use](https://en.wikipedia.org/wiki/Trust_on_first_use) (TOFU) authentication scheme:
-
-- Administrators can enroll a device and generate a custom registration link for a specific user. (Registration links are only valid for the selected user.)
-- When a user registers their device with a registration link, the device will automatically be approved following the TOFU authentication scheme.
-
-## Manage devices (Enterprise)
-
-When an administrator enrolls a device, the Enterprise Console displays the device's status as **Pending Enrollment**.
-
-When a user visits the registration link and registers their device, the Enterprise Console updates the device's status to **Approved**.
-
-If an administrator deletes a device, the device will be revoked and the link becomes invalid.
-
-## Enroll devices as an administrator (Enterprise)
-
-Enterprise users can build policies that only grant access to a route if a user's device is approved in the Enterprise Console. (See [Device Matcher](/docs/capabilities/ppl#device-matcher) for more information.)
-
-The Enterprise Console's **Manage Devices** GUI provides a dashboard where administrators can enroll devices and generate custom registration links for users in their directory.
-
-:::enterprise
-
-Before you can generate device registration links for users within your directory, you must sync your directory data first.
-
-See [**Directory Sync**](/docs/capabilities/directory-sync) for more information.
-
-:::
-
-To enroll a new device:
-
-1. In the Console sidebar, select **Devices**
-
-2. Select **NEW ENROLLMENT**
-
-![Enroll devices](./img/webauthn/admin-enroll-1.png)
-
-3. In the **New Enrollment** window:
-
-**Select Users**: Select a user to send a registration link (the link is only valid for the selected user) <br /> **Route**: Enter a pre-configured route from your Console; Pomerium will use this route to create the custom registration link <br /> **Redirect URL** (optional): Enter a route that users will redirect to after registering their device <br /> **Enrollment Type**:
-
-- Select **Any** to allow a user to register any device
-- Select **Secure Enclave Only** to restrict the user to secure enclaves
-
-![Select new enrollment](./img/webauthn/new-enrollment.png)
-
-4. Select **SUBMIT** to get the registration link
-
-![Enrollment created](./img/webauthn/enrollment-created.png)
-
-Give the link to the user.
-
-## Enroll device as a user
-
-If a Pomerium route [requires device authentication](/docs/capabilities/ppl#device-matcher), the user must register a [trusted execution environment](/docs/concepts/device-identity#authenticated-device-types) (**TEE**) device before accessing the route. Registration differs depending on the device.
-
-The steps below cover enrollment of a device by a user. This is available for both Pomerium Core and [Pomerium Enterprise](/docs/deploy/enterprise/install) installations. However, Enterprise users may also receive registration links [generated by their administrators](/docs/integrations/device-context/device-identit), which will mark the newly enrolled device as approved in the Enterprise Console.
-
-1. Users are prompted to register a new device when accessing a route that requires device authentication:
-
-   ![The WebAuthn Registration page with no devices registered](img/webauthn/no-device.png)
-
-   Users can also access the registration page from the special `.pomerium` endpoint available on any route at the bottom of the page:
-
-   ![The Device Credentials section of the .pomerium endpoint with the WebAuthn link highlighted](img/webauthn/device-credentials-empty-highlight.png)
-
-1. Select **Register New Device**. Your browser will prompt you to provide access to a device. This will look different depending on the browser, operating system, and device type:
-
-   <Tabs>
-
-   <TabItem value="Windows"  label="Windows">
-
-   ![The device authentication prompt on Windows](img/webauthn/security-key-windows.png)
-
-   </TabItem>
-
-   <TabItem value="Chrome"  label="Chrome">
-
-   ![The device authentication prompt in Google Chrome](img/webauthn/security-key-google.png)
-
-   </TabItem>
-
-   <TabItem value="Firefox"  label="Firefox">
-
-   ![The device authentication prompt in Firefox](img/webauthn/security-key-firefox.png)
-
-   </TabItem>
-
-   <TabItem value="ChromeOS"  label="ChromeOS">
-
-   ![The device authentication prompt on ChromeOS](img/webauthn/security-key-chromebook.png)
-
-   </TabItem>
-
-   </Tabs>
-
-### Find the device ID
-
-If a route's policy is configured to only allow specific device IDs, you will see a `450` error even after registering:
-
-![450 device not authorized error screen](img/webauthn/450-error.png)
-
-From the `.pomerium` endpoint you can copy your device ID to provide to your Pomerium administrator.
-
-![Device ID list at /.pomerium](img/webauthn/device-id-list.png)
-
-You can also delete the ID for devices that should no longer be associated with your account.
-
 [android-keystore]: https://source.android.com/security/keystore
 [apple-enclave]: https://support.apple.com/guide/security/secure-enclave-sec59b0b31ff/web
 [apple-passkeys]: https://developer.apple.com/documentation/authenticationservices/public-private_key_authentication/supporting_passkeys