💬 Add section for team management topics

config/routes.rb

@@ -59,6 +59,7 @@
   get "/docs/pipelines/pipelines",                to: redirect("/docs/pipelines")
   get "/docs/pipelines/ignoring-a-commit",        to: redirect("/docs/pipelines/skipping#ignore-a-commit")
   get "/docs/pipelines/parallel-builds",          to: redirect("/docs/tutorials/parallel-builds")
+  get "/docs/pipelines/permissions",              to: redirect("/docs/team-management/permissions")
   get "/docs/pipelines/plugins",                  to: redirect("/docs/plugins")
   get "/docs/pipelines/uploading-pipelines",      to: redirect("/docs/pipelines/defining-steps")
   get "/docs/webhooks/setup",                     to: redirect("/docs/apis/webhooks")

data/nav.yml

@@ -304,12 +304,16 @@
           path: "pipelines/security-overview"
         - name: "Managing secrets"
           path: "pipelines/secrets"
-        - name: "User and team permissions"
-          path: "pipelines/permissions"
         - name: "Webhooks security"
           path: "pipelines/incoming-webhooks"
         - name: "Audit log"
           path: "pipelines/audit-log"
+    - name: "Team management"
+      children:
+        - name: "Overview"
+          path: "team-management"
+        - name: "User and team permissions"
+          path: "team-management/permissions"
     - name: "Governance"
       children:
         - name: "Overview"

pages/apis/rest_api/agents.md

@@ -141,7 +141,7 @@ Success response: `200 OK`
 >📘 Required permissions
 > To stop an agent you need either
 - An Admin user API token with `write_agents` <a href="/docs/apis/managing-api-tokens#token-scopes">scope</a>
-- Or, if you're using <a href="/docs/pipelines/permissions#member-permissions">Member Permissions</a>, a user token with the <em>Stop Agents</em> permission
+- Or, if you're using <a href="/docs/team-management/permissions#member-permissions">Member Permissions</a>, a user token with the <em>Stop Agents</em> permission
 
 Instruct an agent to stop accepting new build jobs and shut itself down.
 

pages/clusters/manage_clusters.md

@@ -53,7 +53,7 @@ To add a pipeline to a cluster:
 
 ### Add maintainers to a cluster
 
-Only Buildkite administrators or users with the [_change organization_ permission](/docs/pipelines/permissions) can create clusters.
+Only Buildkite administrators or users with the [_change organization_ permission](/docs/team-management/permissions) can create clusters.
 
 You can assign other users or teams as a cluster’s maintainers to permit them to manage the cluster. Cluster maintainers can:
 

pages/pipelines/trigger_step.md

@@ -20,7 +20,7 @@ All builds created by a trigger step will have the same author as the parent bui
 * be a member of your organization
 * have a verified email address
 
-If you have [Teams](/docs/pipelines/permissions) enabled in your organization, *one* of the following conditions must be met:
+If you have [Teams](/docs/team-management/permissions) enabled in your organization, *one* of the following conditions must be met:
 
 * The authoring user must have 'Build' permission on *every* pipeline that will be triggered
 * The triggering build has no creator and no unblocker, *and* the source pipeline and the target pipeline share a team that can 'Build'

pages/team_management.md

@@ -0,0 +1,10 @@
+---
+toc: false
+---
+
+# Team management overview
+
+Team management is fundamental in CI/CD tools to ensure streamlined processes, proper access controls, and efficient collaboration. Buildkite provides features for your team management needs:
+
+- [User and team permissions](/docs/team-management/permissions)
+- [Managing API access tokens](/docs/apis/managing-api-tokens) (under the APIs section)

pages/test_analytics/permissions.md

@@ -2,7 +2,7 @@
 
 Customers on the Buildkite [Business and Enterprise](https://buildkite.com/pricing) plans can manage permissions using [Teams](#permissions-with-teams). Enterprise customers can set fine-grained user permissions for their organization with the [Member Permissions](#member-permissions) page.
 
-For more information on enabling Teams for your organization, please see the [Users and Teams section of Pipelines documentation](/docs/pipelines/permissions).
+For more information on enabling Teams for your organization, please see the [Users and Teams section of Pipelines documentation](/docs/team-management/permissions).
 
 
 ## Permissions with teams