[v18] MWI Docs: Tidy/rearrange reference section (#60870)

docs/config.json

@@ -222,12 +222,12 @@
     },
     {
       "source": "/machine-id/reference/telemetry/",
-      "destination": "/reference/machine-workload-identity/machine-id/telemetry/",
+      "destination": "/reference/machine-workload-identity/telemetry/",
       "permanent": true
     },
     {
       "source": "/machine-id/reference/v16-upgrade-guide/",
-      "destination": "/reference/machine-workload-identity/machine-id/v16-upgrade-guide/",
+      "destination": "/reference/machine-workload-identity/",
       "permanent": true
     },
     {
@@ -697,7 +697,7 @@
     },
     {
       "source": "/machine-workload-identity/machine-id/deployment/bound-keypair/",
-      "destination": "/reference/machine-workload-identity/machine-id/bound-keypair/getting-started/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/getting-started/",
       "permanent": true
     },
     {
@@ -769,6 +769,66 @@
       "destination": "/machine-workload-identity/mwi-ci-cd/",
       "permanent": true
     },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/gitlab/",
+      "destination": "/reference/deployment/join-methods/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/github-actions/",
+      "destination": "/reference/deployment/join-methods/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/",
+      "destination": "/reference/machine-workload-identity/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/configuration/",
+      "destination": "/reference/machine-workload-identity/configuration/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/diagnostics-service/",
+      "destination": "/reference/machine-workload-identity/diagnostics-service/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/telemetry/",
+      "destination": "/reference/machine-workload-identity/telemetry/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/bound-keypair/admin-guide/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/admin-guide/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/bound-keypair/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/bound-keypair/concepts/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/concepts/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/bound-keypair/getting-started/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/getting-started/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/bound-keypair/static-keys/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/static-keys/",
+      "permanent": true
+    },
+    {
+      "source": "/reference/machine-workload-identity/machine-id/v16-upgrade-guide/",
+      "destination": "/reference/machine-workload-identity/",
+      "permanent": true
+    },
     {
       "source": "/admin-guides/deploy-a-cluster/access-graph/",
       "destination": "/identity-security/access-graph/",
@@ -1716,57 +1776,57 @@
     },
     {
       "source": "/reference/machine-id/bound-keypair/admin-guide/",
-      "destination": "/reference/machine-workload-identity/machine-id/bound-keypair/admin-guide/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/admin-guide/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/bound-keypair/",
-      "destination": "/reference/machine-workload-identity/machine-id/bound-keypair/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/bound-keypair/concepts/",
-      "destination": "/reference/machine-workload-identity/machine-id/bound-keypair/concepts/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/concepts/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/bound-keypair/getting-started/",
-      "destination": "/reference/machine-workload-identity/machine-id/bound-keypair/getting-started/",
+      "destination": "/reference/machine-workload-identity/bound-keypair/getting-started/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/configuration/",
-      "destination": "/reference/machine-workload-identity/machine-id/configuration/",
+      "destination": "/reference/machine-workload-identity/configuration/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/diagnostics-service/",
-      "destination": "/reference/machine-workload-identity/machine-id/diagnostics-service/",
+      "destination": "/reference/machine-workload-identity/diagnostics-service/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/github-actions/",
-      "destination": "/reference/machine-workload-identity/machine-id/github-actions/",
+      "destination": "/reference/deployment/join-methods/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/gitlab/",
-      "destination": "/reference/machine-workload-identity/machine-id/gitlab/",
+      "destination": "/reference/deployment/join-methods/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/",
-      "destination": "/reference/machine-workload-identity/machine-id/",
+      "destination": "/reference/machine-workload-identity/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/telemetry/",
-      "destination": "/reference/machine-workload-identity/machine-id/telemetry/",
+      "destination": "/reference/machine-workload-identity/telemetry/",
       "permanent": true
     },
     {
       "source": "/reference/machine-id/v16-upgrade-guide/",
-      "destination": "/reference/machine-workload-identity/machine-id/v16-upgrade-guide/",
+      "destination": "/reference/machine-workload-identity/",
       "permanent": true
     },
     {

docs/pages/machine-workload-identity/getting-started.mdx

@@ -268,10 +268,8 @@ $ tctl create -f join_token.yaml
 
 ## Step 5/5 Access a resource from GitHub Actions
 
-We have several published
-[Actions](../reference/machine-workload-identity/machine-id/github-actions.mdx#github-actions-helpers)
-for convenience, but for this guide we will look at things explicitly to aid
-understanding.
+We have several published [Actions](../reference/deployment/join-methods.mdx#github-actions-helpers)
+for convenience, but for this guide we will look at things explicitly to aid understanding.
 
 Within your GitHub repository, you'll create two different files:
 
@@ -474,10 +472,7 @@ without distributing long-lived credentials, making the process more secure and
   configuring `tbot` in a production-ready way for your platform.
 - Check out the [access guides](./machine-id/access-guides/access-guides.mdx) to learn about configuring
   `tbot` for other use cases than SSH and Kubernetes.
-- Read the [configuration
-  reference](../reference/machine-workload-identity/machine-id/configuration.mdx)
-  to explore all the available configuration options.
-- Learn how [Workload
-  Identities](../machine-workload-identity/workload-identity/introduction.mdx)
-  enable the same capabilities for resources like cloud APIs that can't be
-  protected with the Teleport proxy.
+- Read the [configuration reference](../reference/machine-workload-identity/configuration.mdx) to explore
+  all the available configuration options.
+- Learn how [Workload Identities](../machine-workload-identity/workload-identity/introduction.mdx) enable the same capabilities
+  for resources like cloud APIs that can't be protected with the Teleport proxy.

docs/pages/machine-workload-identity/machine-id/access-guides/ansible-awx.mdx

@@ -196,7 +196,7 @@ data:
 ```
 
 For more information on the possible values in this config file, see Machine
-ID's [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx).
+ID's [configuration reference](../../../reference/machine-workload-identity/configuration.mdx).
 
 <Admonition type="info" title="About the ssh-multiplexer">
 Machine ID's `ssh-multiplexer` service is used to improve performance when
@@ -205,7 +205,7 @@ opening many SSH connections. It provides a Unix socket which the
 shared connection to Teleport. The SSH config written to
 `/tbot-output/ssh_config` will be automatically configured to do this.
 
-See the [reference page](../../../reference/machine-workload-identity/machine-id/configuration.mdx#ssh-multiplexer)
+See the [reference page](../../../reference/machine-workload-identity/configuration.mdx#ssh-multiplexer)
 to learn more about the `ssh-multiplexer` service.
 </Admonition>
 
@@ -501,7 +501,7 @@ We've configured the `tbot` client to provide its own multiplexer (via the
 ## Next Steps
 
 - Learn more about [deploying Machine ID in Kubernetes](../deployment/kubernetes.mdx)
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.
 
 {/* see also: https://github.com/ansible/awx-logos/blob/master/TRADEMARKS.md */}

docs/pages/machine-workload-identity/machine-id/access-guides/ansible.mdx

@@ -274,7 +274,7 @@ spec:
 
 ## Next steps
 
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.
 - If you use Ansible AWX or Ansible Automation Platform, read our
   [dedicated Ansible AWX Guide](./ansible-awx.mdx).

docs/pages/machine-workload-identity/machine-id/access-guides/applications.mdx

@@ -226,5 +226,5 @@ has been configured to use both the client certificate and key.
   your bot may access.
 - Configure [JWTs](../../../enroll-resources/application-access/jwt/introduction.mdx) for your
   Application to remove the need for additional login credentials.
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.

docs/pages/machine-workload-identity/machine-id/access-guides/argocd.mdx

@@ -334,7 +334,7 @@ groups.
 
 ## Next steps
 
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx)
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx)
   to explore all the available configuration options.
 - Read the [Teleport Kubernetes RBAC guide](../../../enroll-resources/kubernetes-access/controls.mdx)
   for more details on controlling Kubernetes access.

docs/pages/machine-workload-identity/machine-id/access-guides/databases.mdx

@@ -268,5 +268,5 @@ access controls.
 
 ## Next steps
 
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.

docs/pages/machine-workload-identity/machine-id/access-guides/kubernetes.mdx

@@ -209,7 +209,7 @@ this format is compatible with most Kubernetes tools including:
 
 ## Next steps
 
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.
 - Read the [Teleport Kubernetes RBAC guide](../../../enroll-resources/kubernetes-access/controls.mdx)
   for more details on controlling Kubernetes access.

docs/pages/machine-workload-identity/machine-id/access-guides/mcp.mdx

@@ -207,5 +207,5 @@ MCP client you are using.
 
 - Read the [MCP access documentation](../../../enroll-resources/mcp-access/mcp-access.mdx)
 to learn more about Teleport's MCP integration and RBAC controls.
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
 all the available configuration options for `tbot`.

docs/pages/machine-workload-identity/machine-id/access-guides/ssh.mdx

@@ -172,5 +172,5 @@ SSH client certificates and either ProxyCommand or ProxyJump functionality.
 
 ## Next steps
 
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.

docs/pages/machine-workload-identity/machine-id/access-guides/tctl.mdx

@@ -149,5 +149,5 @@ $ tctl get role/tctl-test
 
 - Explore the [`tctl` reference](../../../reference/cli/tctl.mdx) to discover all
   `tctl` can do.
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available `tbot` configuration options.

docs/pages/machine-workload-identity/machine-id/deployment/aws.mdx

@@ -130,6 +130,6 @@ Replace:
 
 - Follow the [access guides](../access-guides/access-guides.mdx) to finish configuring `tbot` for
   your environment.
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.
-- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/machine-id/telemetry.mdx)
+- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/telemetry.mdx)

docs/pages/machine-workload-identity/machine-id/deployment/azure-devops.mdx

@@ -198,6 +198,6 @@ exit.
   [join method reference page.](../../../reference/deployment/join-methods.mdx#azure-devops-azure_devops)
 - Follow the [access guides](../access-guides/access-guides.mdx) to finish configuring `tbot` for
 your environment.
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
 all the available configuration options.
-- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/machine-id/telemetry.mdx)
+- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/telemetry.mdx)

docs/pages/machine-workload-identity/machine-id/deployment/azure.mdx

@@ -132,6 +132,6 @@ Replace:
 
 - Follow the [access guides](../access-guides/access-guides.mdx) to finish configuring `tbot` for
   your environment.
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.
-- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/machine-id/telemetry.mdx)
+- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/telemetry.mdx)

docs/pages/machine-workload-identity/machine-id/deployment/bitbucket.mdx

@@ -158,7 +158,7 @@ credentials are needed in multiple steps.
 
 - Follow the [access guides](../access-guides/access-guides.mdx) to finish configuring `tbot` for
   your environment.
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.
 - For more information about Bitbucket Pipelines itself, read
   [their documentation](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/).

docs/pages/machine-workload-identity/machine-id/deployment/circleci.mdx

@@ -216,8 +216,8 @@ resources in your Teleport cluster that your CI/CD needs to interact with.
 
 - Follow the [access guides](../access-guides/access-guides.mdx) to finish configuring `tbot` for
   your environment.
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.
 - For more information about CircleCI itself, read
   [their documentation](https://circleci.com/docs/).
-- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/machine-id/telemetry.mdx)
+- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/telemetry.mdx)

docs/pages/machine-workload-identity/machine-id/deployment/deployment.mdx

@@ -46,7 +46,7 @@ Choose a guide based on the platform where you intend to run Machine ID.
 
 If a specific guide does not exist for your platform, the [Linux
 guide](linux.mdx) is compatible with most platforms. For
-custom approaches, you can also read the [Machine ID Reference](../../../reference/machine-workload-identity/machine-id/machine-id.mdx)
+custom approaches, you can also read the [Machine ID Reference](../../../reference/machine-workload-identity/machine-workload-identity.mdx)
 and [Architecture](../../../reference/architecture/machine-id-architecture.mdx) to plan your deployment.
 
 <TileGrid
@@ -113,7 +113,7 @@ and [Architecture](../../../reference/architecture/machine-id-architecture.mdx)
     },
     {
       icon: <Icon name="lock" size="xl" />,
-      to: "../../../reference/machine-workload-identity/machine-id/bound-keypair/getting-started",
+      to: "../../../reference/machine-workload-identity/bound-keypair/getting-started",
       name: "Bound Keypair Joining",
     }
   ]}
@@ -167,7 +167,7 @@ Read the following guides for how to deploy Machine ID on a continuous integrati
     },
     {
       icon: <Icon name="lock" size="xl" />,
-      to: "../../../reference/machine-workload-identity/machine-id/bound-keypair/static-keys",
+      to: "../../../reference/machine-workload-identity/bound-keypair/static-keys",
       name: "Bound Keypair static keys (Generic)",
     }
   ]}
@@ -178,4 +178,4 @@ If your CI/CD provider does not have a dedicated join method listed above,
 consider using [Bound Keypair static keys][bound-keypair-static] as a fallback.
 </Admonition>
 
-[bound-keypair-static]: ../../../reference/machine-workload-identity/machine-id/bound-keypair/static-keys.mdx
+[bound-keypair-static]: ../../../reference/machine-workload-identity/bound-keypair/static-keys.mdx

docs/pages/machine-workload-identity/machine-id/deployment/gcp.mdx

@@ -133,6 +133,6 @@ Replace:
 
 - Follow the [access guides](../access-guides/access-guides.mdx) to finish configuring `tbot` for
   your environment.
-- Read the [configuration reference](../../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
+- Read the [configuration reference](../../../reference/machine-workload-identity/configuration.mdx) to explore
   all the available configuration options.
-- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/machine-id/telemetry.mdx)
+- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../../reference/machine-workload-identity/telemetry.mdx)