vantagecompute · wardbryan3 · Jul 1, 2026 · Jun 29, 2026 · Jun 29, 2026 · Jun 29, 2026
diff --git a/docs/explanation/cli-architecture.md b/docs/explanation/cli-architecture.md
diff --git a/docs/explanation/concepts/compute-and-clusters.md b/docs/explanation/concepts/compute-and-clusters.md
@@ -9,13 +9,7 @@ A cluster is a Kubernetes or Slurm cluster Vantage manages on your behalf. Compu
 
 ## Cluster types
 
-Vantage provisions three kinds of clusters. Your choice determines the scheduler and which workloads can run.
-
-| Type | Scheduler | Best for |
-|---|---|---|
-| Slurm | Slurm (batch jobs) | Traditional HPC, simulations, MPI, batch pipelines |
-| Kubernetes | Kubernetes | Workbench sessions, ML training, containerized workloads |
-| Slurm on Kubernetes | Slurm inside K8s | HPC scheduling on cloud-native, auto-scaled infrastructure |
+Vantage provisions three kinds of clusters, Slurm, Kubernetes, and Slurm on Kubernetes. Your choice determines the scheduler and which workloads can run. For the comparison table and the status lifecycle, see [Clusters concepts](/explanation/clusters).
 
 ## Compute profiles
 
@@ -25,14 +19,13 @@ Profiles live at the workspace level. Your admin defines which profiles are avai
 
 ## Compute providers
 
-Providers are the physical infrastructure Vantage provisions clusters on.
-
-| Provider | What it's for |
-|---|---|
-| Public clouds (AWS, Azure, GCP) | Elastic capacity, global regions, spot pricing |
-| On-premises / LXD / Multipass / Juju | Your own hardware or local VMs, Ansible, Terraform, manual, Multipass, or Charmed HPC |
-| Vantage partners (atNorth, BuzzHPC, RCI) | Pre-integrated managed colocation and HPC |
+Providers are the physical infrastructure Vantage provisions clusters on, public clouds, on-premises, and partner colocation. For the provider comparison table and validity lifecycle, see [Clusters concepts](/explanation/clusters) and [Compute providers concepts](/explanation/compute-providers).
 
 ## Regions and availability
 
 Cloud clusters run in the region you select during creation. Slurm clusters can span multiple availability zones within a region. On-premises clusters report their location as configured by your admin.
+
+## Cross-references
+
+- [Clusters concepts](/explanation/clusters): cluster types, status lifecycle, partitions and compute pools, cost
+- [Compute providers concepts](/explanation/compute-providers): cloud accounts, provider types, validity
diff --git a/docs/explanation/concepts/jobs-and-pipelines.md b/docs/explanation/concepts/jobs-and-pipelines.md
@@ -25,6 +25,7 @@ A pipeline is a directed acyclic graph (DAG) of steps. Each step runs a containe
 
 Unlike a single job that runs a self-contained workload, a pipeline coordinates multiple stages. Use pipelines for workflows that combine ingestion, preprocessing, training, evaluation, and deployment in sequence.
 
-## Where to go next
+## Cross-references
 
-Jobs, scripts, templates, and submissions have their own full section under [Platform > Jobs](/reference/jobs). Pipelines are covered under [Platform > Workbench > Pipelines](/reference/workbench/pipelines). This page is just the high-level picture.
+- [Jobs concepts](/explanation/jobs): scripts, templates, submissions, and the pipeline flow in detail
+- Jobs, scripts, templates, and submissions have their own full section under [Platform > Jobs](/reference/jobs). Pipelines are covered under [Platform > Workbench > Pipelines](/reference/workbench/pipelines). This page is just the high-level picture.
diff --git a/docs/explanation/concepts/teams-and-iam.md b/docs/explanation/concepts/teams-and-iam.md
@@ -15,15 +15,13 @@ The **Teams** page lists every team you're a member of. Team admins can add and
 
 ## Roles and permissions
 
-Vantage uses role-based access control (RBAC). A role is a set of permissions, create sessions, submit jobs, manage storage, administer teams, that you assign to users within a team.
-
-| Role | Typical permissions |
-|---|---|
-| Admin | Full control, manage members, roles, quota, billing |
-| Engineer | Create and run workloads, manage their own resources |
-| Viewer | Read-only access to cluster status, jobs, and usage |
-| Custom | Team-specific permission sets defined by the admin |
+Vantage uses role-based access control (RBAC). A role is a set of permissions, create sessions, submit jobs, manage storage, administer teams, that you assign to users within a team. Built-in roles cover Admin, Engineer, and Viewer; team admins can define custom permission sets. For the role inventory and the IAM permission-group inventory, see [Teams concepts](/explanation/teams) and [IAM concepts](/explanation/iam).
 
 ## Resource ownership
 
 Every resource tracks who created it and which team it belongs to. Ownership controls who can modify or delete it. When you leave a team, your personal resources remain, the team admin can reassign ownership if needed.
+
+## Cross-references
+
+- [Teams concepts](/explanation/teams): team-as-ownership-boundary, membership across teams, resource visibility
+- [IAM concepts](/explanation/iam): permission groups, authentication, SCIM provisioning
diff --git a/docs/explanation/concepts/workbench-ml-stack.md b/docs/explanation/concepts/workbench-ml-stack.md
@@ -108,7 +108,6 @@ The integration cost of stitching these together, shared auth, consistent resour
 
 ## Cross-references
 
-- [Workbench overview](/reference/workbench): the full index of Workbench sections and links
-- [Workbench concepts](/explanation/workbench/overview): the seven mental models behind Workbench (workspace, preset, lifecycle, cost, and others)
+- [Workbench overview](/explanation/workbench): the seven mental models behind Workbench (workspace, preset, lifecycle, cost, and others)
 - [Compute and clusters](/explanation/concepts/compute-and-clusters): the infrastructure layer underneath Workbench
 - [Jobs and pipelines](/explanation/concepts/jobs-and-pipelines): how jobs and pipelines work outside of Workbench (Slurm, scripts, templates)
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -5,32 +5,31 @@ description: Conceptual guides and mental models for understanding Vantage.
 
 # Explanation
 
-Explanation docs answer why something exists, how it works, and how concepts relate to each other.
+Explanation docs answer why something exists, how it works, and how concepts relate to each other. Read these once and the rest of the docs make more sense.
 
 ## Core concepts
 
+Cross-cutting mental models that span every Vantage product area.
+
+- [Overview](/explanation/concepts)
 - [Workspaces](/explanation/concepts/workspaces)
 - [Jobs and pipelines](/explanation/concepts/jobs-and-pipelines)
 - [Compute and clusters](/explanation/concepts/compute-and-clusters)
 - [Teams and IAM](/explanation/concepts/teams-and-iam)
-- [Slurm vs. Kubernetes](/explanation/concepts/slurm-vs-kubernetes)
 - [Why Teams and IAM](/explanation/concepts/why-teams-and-iam)
-- [Workbench ML Stack](/explanation/concepts/workbench-ml-stack)
+- [Slurm vs. Kubernetes](/explanation/concepts/slurm-vs-kubernetes)
+- [Workbench ML stack](/explanation/concepts/workbench-ml-stack)
 
 ## By area
 
-- [Compute providers](/explanation/compute-providers)
+Concept deep-dives for each product area: tables, lifecycles, and modes.
+
 - [Clusters](/explanation/clusters)
 - [Jobs](/explanation/jobs)
-- [Workbench](/explanation/workbench/overview)
+- [Workbench](/explanation/workbench)
 - [Storage](/explanation/storage)
 - [Federations](/explanation/federations)
-- [IAM](/explanation/iam)
+- [Compute providers](/explanation/compute-providers)
 - [Teams](/explanation/teams)
+- [IAM](/explanation/iam)
 - [Licenses](/explanation/licenses)
-
-## Developer tools
-
-- [CLI architecture](/explanation/cli-architecture)
-- [SDK overview](/reference/developer-tools/sdk)
-- [API overview](/reference/developer-tools/api)
diff --git a/docs/explanation/workbench/overview.mdx → docs/explanation/workbench.mdx b/docs/explanation/workbench/overview.mdx → docs/explanation/workbench.mdx
diff --git a/docs/how-to-guides/cloud-accounts/connect-cloud-account.mdx b/docs/how-to-guides/cloud-accounts/connect-cloud-account.mdx
@@ -414,7 +414,7 @@ Click `Create Cloud Account`.
 </div>
 </div>
 
-After creating the account, use one of the on-premises cluster setup methods (Ansible, Terraform, Kubernetes, Juju, or Multipass) to connect your infrastructure. See [On-premises clusters](/reference/clusters/on-premises) for setup guides.
+After creating the account, use one of the on-premises cluster setup methods (Ansible, Terraform, Kubernetes, Juju, or Multipass) to connect your infrastructure. See [On-premises clusters](/how-to-guides/clusters/on-premises) for setup guides.
 
 Success looks like this: the new account appears in `uvx v8x cloud-account list` with provider `on-premises` and is ready to back a cluster.
 

diff --git a/docs/how-to-guides/clusters/federations/tutorials.mdx b/docs/how-to-guides/clusters/federations/tutorials.mdx
@@ -117,7 +117,7 @@ Handle peak demand by pairing a small on-premises cluster with one or more cloud
 
 ### Connect your on-premises cluster
 
-Install the Vantage connector on your infrastructure. See the [on-premises guide](/reference/clusters/on-premises) for setup instructions.
+Install the Vantage connector on your infrastructure. See the [on-premises guide](/how-to-guides/clusters/on-premises) for setup instructions.
 
 </div>
 <div className="guide-step">

diff --git a/docs/how-to-guides/clusters/get-started.mdx b/docs/how-to-guides/clusters/get-started.mdx
@@ -73,7 +73,7 @@ After your first cluster is connected, dive deeper into your cluster type:
 | [Creating a Kubernetes cluster](/how-to-guides/clusters/kubernetes/create) | Provider-specific steps for K8s |
 | [Slurm partitions](/reference/clusters/slurm/partitions) | Managing job queues |
 | [Kubernetes compute pools](/reference/clusters/kubernetes/node-groups) | Managing compute pools |
-| [On-Premises clusters](/reference/clusters/on-premises) | Ansible, Terraform, Kubernetes, Juju, Multipass, or manual setup |
+| [On-Premises clusters](/how-to-guides/clusters/on-premises) | Ansible, Terraform, Kubernetes, Juju, Multipass, or manual setup |
 
 :::tip
 Cloud cluster nodes bill while running, even idle ones. Set the maximum node count for each partition or compute pool conservatively during setup. You can raise it when you're ready to run jobs.

diff --git a/docs/how-to-guides/clusters/kubernetes/create.mdx b/docs/how-to-guides/clusters/kubernetes/create.mdx
@@ -150,10 +150,10 @@ Success looks like this: the cluster enters provisioning, Kubernetes resources b
 
 On-premises Kubernetes clusters connect to Vantage through a lightweight connector deployed on your infrastructure. Vantage does not provision cloud resources, you provide the compute.
 
-For the full setup guide, see [On-Premises clusters](/reference/clusters/on-premises) and use the Kubernetes tab.
+For the full setup guide, see [On-Premises clusters](/how-to-guides/clusters/on-premises) and use the Kubernetes tab.
 
 :::note
-Multipass and Juju on-premises clusters only support Slurm, not Kubernetes. For Kubernetes on your own hardware, use the [On-Premises clusters guide](/reference/clusters/on-premises) and choose the Kubernetes tab.
+Multipass and Juju on-premises clusters only support Slurm, not Kubernetes. For Kubernetes on your own hardware, use the [On-Premises clusters guide](/how-to-guides/clusters/on-premises) and choose the Kubernetes tab.
 :::
 
 </TabItem>
-Original file line number
+Diff line change
@@ Expand Up / @@ -414,7 +414,7 @@ Click `Create Cloud Account`. @@
     </div>
     </div>
-    After creating the account, use one of the on-premises cluster setup methods (Ansible, Terraform, Kubernetes, Juju, or Multipass) to connect your infrastructure. See [On-premises clusters](/reference/clusters/on-premises) for setup guides.
+    After creating the account, use one of the on-premises cluster setup methods (Ansible, Terraform, Kubernetes, Juju, or Multipass) to connect your infrastructure. See [On-premises clusters](/how-to-guides/clusters/on-premises) for setup guides.
     Success looks like this: the new account appears in `uvx v8x cloud-account list` with provider `on-premises` and is ready to back a cluster.
@@ Expand Down @@