diff --git a/docs/how-to-guides/clusters/get-started.mdx b/docs/how-to-guides/clusters/get-started.mdx
index 9dee4a0..7a8afea 100644
--- 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
index f71db62..08bad9f 100644
--- 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.
:::
diff --git a/docs/how-to-guides/clusters/on-premises.mdx b/docs/how-to-guides/clusters/on-premises.mdx
new file mode 100644
index 0000000..08cc502
--- /dev/null
+++ b/docs/how-to-guides/clusters/on-premises.mdx
@@ -0,0 +1,734 @@
+---
+title: On-Premises clusters
+description: Connect your own infrastructure to Vantage using Ansible, Terraform, Kubernetes, Juju, Multipass, or manual setup.
+---
+
+# On-Premises clusters
+
+On-premises clusters run on infrastructure you control, bare-metal servers, local VMs, or LXD containers. Vantage supports multiple methods for connecting your infrastructure, each suited to a different use case and level of automation.
+
+
+
+
+
+
Ansible
+
+
+
+
+
Terraform
+
+
+
+
+
Kubernetes
+
+
+
+
+
Juju
+
+
+
+
+
Multipass
+
+
+
+
+
Manual
+
+
+
+
+## Prerequisites
+
+All on-premises methods require:
+
+- A Vantage account and organization ([Sign up](/tutorial))
+- A configured [On-Premises or LXD Cloud Account](/reference/settings/compute-providers/on-premises)
+- Outbound HTTPS access (port 443) from your infrastructure to Vantage servers
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+
+
+
+
+
+
+
+
+
+Use the [vantage-agents Ansible role](https://github.com/vantagecompute/ansible-role-vantage_agents) to automate connecting your Slurm cluster to Vantage. The role installs and configures both `vantage-agent` and `jobbergate-agent` on your controller node.
+
+### Prerequisites
+
+- An existing Slurm cluster with SSH access to the controller node
+- Ansible 2.9+ installed on your workstation
+- OIDC credentials from your Vantage cluster (client ID and client secret)
+
+### 1. Create a Slurm cluster in Vantage
+
+1. **Open Clusters:** Click **Clusters** in the left sidebar, then click **Slurm** in the cluster type navigation, then click Prepare Cluster.
+
+1. **Configure the cluster:**
+ - Enter a **Cluster Name** (max 27 characters, must be unique).
+ - Select your **On-Premises** or **LXD** cloud account.
+
+1. **Submit:** Click Create Cluster. Note the **OIDC Client ID** and **OIDC Client Secret** from the cluster detail page, you will need these in the next step.
+
+### 2. Install the Ansible role
+
+```bash
+ansible-galaxy install git+https://github.com/vantagecompute/ansible-role-vantage_agents.git,vantage_agents
+```
+
+### 3. Create a playbook
+
+```yaml
+- hosts: util_node
+ become: true
+ vars:
+ oidc_client_id: ""
+ oidc_client_secret: ""
+ cluster_name: ""
+ install_type: "snap" # or "pypi"
+ roles:
+ - role: vantage_agents
+```
+
+### 4. Run the playbook
+
+```bash
+ansible-playbook -i your_inventory your_playbook.yml
+```
+
+### 5. Verify the connection
+
+Once the playbook completes:
+
+- The cluster transitions from `preparing` to `ready` in the Vantage UI
+- Nodes appear in the cluster detail page as they register
+- You can submit jobs and launch notebooks immediately
+
+:::tip
+The Ansible role supports both Snap (default) and PyPI installation methods. Set `install_type: "pypi"` in your playbook vars to use Python virtual environments with systemd services instead of Snap packages.
+:::
+
+### Next steps
+
+- [Manage a Slurm cluster](/reference/clusters/slurm/manage)
+- [Slurm partitions](/reference/clusters/slurm/partitions)
+- [ansible-role-vantage_agents on GitHub](https://github.com/vantagecompute/ansible-role-vantage_agents)
+
+
+
+
+Use the [terraform-vantage-agents module](https://github.com/vantagecompute/terraform-vantage-agents) to automate connecting your Slurm cluster to Vantage. The module SSH-es into your controller node and installs both `vantage-agent` and `jobbergate-agent`.
+
+### Prerequisites
+
+- An existing Slurm cluster with SSH access to the controller node
+- Terraform 1.0+ installed on your workstation
+- OIDC credentials from your Vantage cluster (client ID and client secret)
+
+### 1. Create a Slurm cluster in Vantage
+
+1. **Open Clusters:** Click **Clusters** in the left sidebar, then click **Slurm** in the cluster type navigation, then click Prepare Cluster.
+
+1. **Configure the cluster:**
+ - Enter a **Cluster Name** (max 27 characters, must be unique).
+ - Select your **On-Premises** or **LXD** cloud account.
+
+1. **Submit:** Click Create Cluster. Note the **OIDC Client ID** and **OIDC Client Secret** from the cluster detail page, you will need these in the next step.
+
+### 2. Configure the Terraform module
+
+```hcl
+module "vantage_agents" {
+ source = "github.com/vantagecompute/terraform-vantage-agents"
+
+ ssh_user = var.ssh_user
+ ssh_private_key = file(var.ssh_private_key)
+ host = var.host
+
+ oidc_client_id = var.oidc_client_id
+ oidc_client_secret = var.oidc_client_secret
+ cluster_name = var.cluster_name
+
+ # Optional: set to "pypi" for Python venv + systemd instead of Snap
+ # install_type = "pypi"
+}
+```
+
+### 3. Apply the configuration
+
+```bash
+terraform init
+terraform apply
+```
+
+### 4. Verify the connection
+
+Once Terraform completes:
+
+- The cluster transitions from `preparing` to `ready` in the Vantage UI
+- Nodes appear in the cluster detail page as they register
+- You can submit jobs and launch notebooks immediately
+
+:::tip
+The Terraform module supports both Snap (default) and PyPI installation methods. Set `install_type = "pypi"` to use Python virtual environments with systemd services instead of Snap packages.
+:::
+
+### Next steps
+
+- [Manage a Slurm cluster](/reference/clusters/slurm/manage)
+- [Slurm partitions](/reference/clusters/slurm/partitions)
+- [terraform-vantage-agents on GitHub](https://github.com/vantagecompute/terraform-vantage-agents)
+
+
+
+
+Connect an existing Kubernetes cluster to Vantage. Vantage does not provision cloud resources for on-premises K8s, you provide the compute infrastructure.
+
+### Prerequisites
+
+- An existing Kubernetes cluster with a reachable API server
+- A configured On-Premises or LXD cloud account in Vantage
+- Outbound HTTPS access (port 443) from your cluster to Vantage servers
+
+### 1. Create a Kubernetes cluster in Vantage
+
+1. **Open Clusters:** Click **Clusters** in the left sidebar (the **Kubernetes** view is shown by default), then click Prepare Cluster.
+
+1. **Configure:**
+ - Enter a **Cluster Name**.
+ - Select your **On-Premises** or **LXD** cloud account.
+
+1. **Submit:** Click Create Cluster. The modal closes and you are redirected to the cluster view.
+
+### 2. Connect your cluster
+
+After creating the cluster, the cluster detail page shows that the connection is not yet established and provides instructions for connecting your infrastructure.
+
+Follow the on-screen instructions to install the Vantage connector on your cluster. The connector only needs outbound HTTPS access to Vantage servers (port 443). If your cluster is behind a firewall, ensure outbound connectivity is not blocked.
+
+Once the connector is active:
+
+- The cluster transitions from `preparing` to `ready`
+- Nodes appear in the cluster detail page as they register
+- You can launch notebooks and deploy workloads immediately
+
+:::note
+Multipass and Juju on-premises clusters only support Slurm, not Kubernetes. For Kubernetes on your own hardware, use this method.
+:::
+
+### Troubleshooting
+
+#### Cluster stays in "preparing"
+
+- Verify the connector was installed and is running on your control plane node.
+- Check that port 443 outbound is not blocked by a firewall.
+- Confirm the cloud account credentials are valid.
+
+#### Nodes not appearing
+
+- Install the connector on each worker node, not just the control plane.
+- Check that each node can reach Vantage servers over HTTPS.
+
+### Next steps
+
+- [Manage a Kubernetes cluster](/reference/clusters/kubernetes/manage)
+- [Kubernetes compute pools](/reference/clusters/kubernetes/node-groups)
+
+
+
+
+Deploy a production-like Slurm cluster on your local machine using Juju charms and LXD containers. Charmed HPC provides a full HPC stack, controller, compute, database, REST API, login node, and Vantage integration, all running inside LXD containers on a single host.
+
+### Prerequisites
+
+- Ubuntu 22.04 or 24.04 (host machine)
+- LXD installed and initialised (`lxd init`)
+- Juju snap installed
+- Internet access to download charms and container images
+
+### 1. Bootstrap a Juju controller
+
+```bash
+juju bootstrap lxd
+```
+
+This creates a controller named `lxd-default` inside an LXD container. It manages all models and workloads.
+
+### 2. Add a model for your Slurm cluster
+
+```bash
+juju add-model myslurmcluster
+```
+
+Models are logical environments. Name yours whatever you like, `myslurmcluster` is used throughout this guide.
+
+### 3. Deploy the required charms
+
+Use Ubuntu 24.04 as the base for Slurm charms. MySQL uses Ubuntu 22.04 (charm default).
+
+```bash
+juju deploy slurmctld --base ubuntu@24.04 --channel 25.11/edge
+juju deploy slurmdbd --base ubuntu@24.04 --channel 25.11/edge
+juju deploy mysql --channel 8.0/stable
+juju deploy slurmrestd --base ubuntu@24.04 --channel 25.11/edge
+juju deploy slurmd --base ubuntu@24.04 --channel 25.11/edge
+juju deploy sackd --base ubuntu@24.04 --channel 25.11/edge
+juju deploy jobbergate-agent --channel latest/edge --base ubuntu@24.04
+juju deploy vantage-agent --channel latest/edge --base ubuntu@24.04
+```
+
+### 4. Add relations (integrations)
+
+```bash
+juju relate slurmctld slurmdbd
+juju relate slurmctld slurmrestd
+juju relate slurmctld slurmd
+juju relate slurmdbd mysql
+juju relate sackd slurmctld
+juju relate jobbergate-agent sackd
+juju relate vantage-agent sackd
+```
+
+These connections enable:
+
+- Accounting and configuration sharing
+- REST API access
+- Compute node registration
+- Vantage integration with Slurm
+
+### 5. Configure the charms
+
+#### Compute node initial state
+
+Set slurmd nodes to start in `idle` (ready to run jobs) or `down` (manual resume). Use lowercase only:
+
+```bash
+juju config slurmd default-node-state=idle
+```
+
+#### OIDC credentials (for Vantage integration)
+
+Replace the example values with your real OIDC client ID and secret.
+
+```bash
+juju config jobbergate-agent jobbergate-agent-oidc-client-id=your-client-id
+juju config jobbergate-agent jobbergate-agent-oidc-client-secret=your-client-secret
+juju config vantage-agent vantage-agent-oidc-client-id=your-client-id
+juju config vantage-agent vantage-agent-oidc-client-secret=your-client-secret
+```
+
+#### Vantage cluster name
+
+```bash
+juju config vantage-agent vantage-agent-cluster-name=myslurmcluster
+```
+
+### 6. Monitor deployment
+
+```bash
+juju status --watch 1s
+```
+
+Wait until all applications show `active` and all units are `idle`.
+
+Expected status:
+
+| Application | Expected status |
+|---|---|
+| `slurmctld`, `slurmdbd`, `mysql`, `slurmd`, `slurmrestd`, `sackd` | `active` |
+| `jobbergate-agent`, `vantage-agent` | `active` (once OIDC and cluster name are set) |
+
+### 7. Verify the Slurm cluster
+
+SSH into the controller unit (machine 0):
+
+```bash
+juju ssh 0
+```
+
+Check the partition and nodes:
+
+```bash
+sinfo
+```
+
+You should see the `slurmd` partition and at least one node in `idle` state.
+
+If the node is `down`, resume it:
+
+```bash
+sudo scontrol update nodename=slurmd-0 state=resume
+```
+
+Submit a test job:
+
+```bash
+sbatch -p slurmd --wrap="sleep 10; hostname"
+squeue
+```
+
+After a few seconds, `squeue` should show the job running (`R`) then disappear. Check the output:
+
+```bash
+cat slurm-*.out
+```
+
+Exit the controller:
+
+```bash
+exit
+```
+
+### Troubleshooting
+
+#### Deployment failures
+
+```bash
+juju status
+juju debug-log --include slurmctld
+```
+
+#### Container issues
+
+```bash
+lxc list
+lxc logs
+lxc restart
+```
+
+#### Network connectivity
+
+```bash
+lxc network show lxdbr0
+lxc exec -- ping google.com
+```
+
+#### Slurm services not running
+
+```bash
+juju ssh slurmctld/0
+sudo systemctl status slurmctld
+sudo systemctl status slurmdbd
+sudo systemctl restart slurmctld slurmdbd
+sudo journalctl -u slurmctld -f
+```
+
+### Next steps
+
+- [Submit jobs to your cluster](/reference/jobs)
+- Create a Multipass cluster using the Multipass tab below for simpler single-node setups
+- Connect manually using the Manual tab below for production on-premises deployments
+
+
+
+
+Deploy a single-node Slurm cluster in a Multipass VM on your local machine. Multipass provides lightweight Ubuntu VMs managed through a simple CLI, ideal for development, testing, and learning Vantage without cloud infrastructure.
+
+Multipass clusters are created and managed entirely through the terminal using the v8x.
+
+:::tip When to use Multipass
+
+Use Multipass when you want to:
+
+- Try Vantage without cloud infrastructure
+- Develop and test Slurm job scripts locally
+- Learn HPC workflows on your laptop
+
+For a multi-node HPC environment, use the Juju tab below instead. For connecting existing production hardware, use the Manual tab below.
+:::
+
+### Prerequisites
+
+- A Vantage account and organization ([Sign up](/tutorial))
+- A Linux, macOS, or Windows machine with at least 8 GB RAM and 20 GB disk space
+- [Snap](https://snapcraft.io/docs/installing-snapd) package manager (Linux) or Homebrew (macOS)
+
+### 1. Install v8x
+
+```bash
+uvx v8x
+```
+
+Verify the installation:
+
+```bash
+uvx v8x version
+```
+
+Log in to your Vantage account:
+
+```bash
+uvx v8x login
+```
+
+### 2. Install Multipass
+
+```bash
+# Linux (via snap)
+sudo snap install multipass
+
+# macOS (via Homebrew)
+brew install --cask multipass
+
+# Windows, download the installer from https://multipass.run/install
+```
+
+Verify the installation:
+
+```bash
+multipass --version
+```
+
+### 3. Deploy the cluster
+
+Deploy a single-node Slurm cluster:
+
+```bash
+uvx v8x app deploy slurm-multipass-localhost
+```
+
+Monitor the deployment progress:
+
+```bash
+uvx v8x app status slurm-multipass-localhost
+```
+
+Wait until the VM is running and Slurm services are ready:
+
+```bash
+multipass list
+```
+
+The output should show the VM in a `Running` state.
+
+#### Custom resources
+
+By default, the cluster uses 4 CPUs, 8 GB RAM, and 50 GB disk. Customize resources during deployment:
+
+```bash
+uvx v8x app deploy slurm-multipass-localhost \
+ --cpus=4 \
+ --memory=8G \
+ --disk=50G
+```
+
+### 4. Access the cluster
+
+Connect to the VM:
+
+```bash
+multipass shell slurm-node
+```
+
+Or use SSH:
+
+```bash
+ssh ubuntu@$(multipass info slurm-node --format json | jq -r '.info."slurm-node".ipv4[0]')
+```
+
+### 5. Verify Slurm
+
+Once connected to the VM, verify that Slurm is running:
+
+```bash
+sinfo
+squeue
+```
+
+Submit a test job:
+
+```bash
+srun --nodes=1 --ntasks=1 hostname
+```
+
+Or submit a batch job:
+
+```bash
+sbatch <
+
+
+Connect your existing Slurm or Kubernetes cluster to Vantage by manually installing the Vantage connector on your infrastructure. This method gives you full control over the installation process and works with any Linux server that meets the prerequisites.
+
+### Prerequisites
+
+- A Vantage account and organization ([Sign up](/tutorial))
+- A configured [On-Premises or LXD Cloud Account](/reference/settings/compute-providers/on-premises)
+- Outbound HTTPS access (port 443) from your infrastructure to Vantage servers
+- SSH access to your cluster nodes
+
+### Create a Slurm cluster
+
+1. **Open Clusters:** Click **Clusters** in the left sidebar, then click **Slurm** in the cluster type navigation, then click Prepare Cluster.
+
+1. **Configure the cluster:**
+ - Enter a **Cluster Name** (max 27 characters, must be unique).
+ - Select your **On-Premises** or **LXD** cloud account.
+
+1. **Submit:** Click Create Cluster. A success toast confirms the cluster was created. The modal closes and you are redirected to the cluster view.
+
+### Create a Kubernetes cluster
+
+1. **Open Clusters:** Click **Clusters** in the left sidebar (the **Kubernetes** view is shown by default), then click Prepare Cluster.
+
+1. **Configure:**
+ - Enter a **Cluster Name**.
+ - Select your **On-Premises** or **LXD** cloud account.
+
+1. **Submit:** Click Create Cluster. The modal closes and you are redirected to the cluster view.
+
+### Connect your cluster
+
+After creating the cluster, the cluster detail page shows a message that the connection is not yet established and provides a link to installation instructions. Follow those instructions to install the Vantage connector on your cluster node.
+
+The connector only needs outbound HTTPS access to Vantage servers (port 443). If your cluster is behind a firewall, ensure outbound connectivity is not blocked.
+
+Once the connector is active:
+
+- The cluster transitions from `preparing` to `ready`
+- Nodes appear in the cluster detail page as they register
+- You can submit jobs and launch notebooks immediately
+
+:::tip
+On-premises clusters report their location as configured by your admin. Partitions and compute pools are configured post-creation from the cluster detail page.
+:::
+
+### Troubleshooting
+
+#### Cluster stays in "preparing"
+
+- Verify the connector was installed and is running on your head node.
+- Check that port 443 outbound is not blocked by a firewall.
+- Confirm the cloud account credentials are valid.
+
+#### Nodes not appearing
+
+- Install the connector on each compute node, not just the head node.
+- Check that each node can reach Vantage servers over HTTPS.
+
+### Next steps
+
+- [Manage a Slurm cluster](/reference/clusters/slurm/manage)
+- [Manage a Kubernetes cluster](/reference/clusters/kubernetes/manage)
+- [Slurm partitions](/reference/clusters/slurm/partitions)
+- [Kubernetes compute pools](/reference/clusters/kubernetes/node-groups)
+
+
+
+
+## Which method should I use?
+
+- **Ansible:** You manage your Slurm infrastructure with Ansible and want automated, repeatable deployments.
+- **Terraform:** You manage your Slurm infrastructure with Terraform and want infrastructure-as-code deployments.
+- **Kubernetes:** You have an existing Kubernetes cluster and want to connect it to Vantage.
+- **Juju (Charmed HPC):** You want a multi-node Slurm environment that simulates a production HPC cluster, running locally in LXD containers.
+- **Multipass:** You want a quick, single-node Slurm environment on your laptop for development and testing.
+- **Manual:** You have existing servers or bare-metal hardware and want full control over the installation process. Supports both Slurm and Kubernetes.
+
+:::tip
+Ansible, Terraform, and Juju clusters are configured through their respective tooling. Manual clusters are configured through the Vantage web UI. Multipass clusters are created through the v8x.
+:::
\ No newline at end of file
diff --git a/docs/how-to-guides/clusters/slurm/create.mdx b/docs/how-to-guides/clusters/slurm/create.mdx
index e020898..5774e19 100644
--- a/docs/how-to-guides/clusters/slurm/create.mdx
+++ b/docs/how-to-guides/clusters/slurm/create.mdx
@@ -170,7 +170,7 @@ Success looks like this: the cluster enters provisioning, the Slurm controller a
On-premises Slurm clusters connect through a lightweight agent deployed on your infrastructure. Vantage does not provision cloud resources, you provide the compute.
-For full setup guides covering manual, Ansible, Terraform, Multipass, and Juju (Charmed HPC) clusters, see [On-Premises clusters](/reference/clusters/on-premises).
+For full setup guides covering manual, Ansible, Terraform, Multipass, and Juju (Charmed HPC) clusters, see [On-Premises clusters](/how-to-guides/clusters/on-premises).
:::tip
On-premises clusters created through the web UI use the manual method. For automated setup, use Ansible or Terraform. For local development and testing, use Multipass or Juju via the Vantage CLI.
diff --git a/docs/how-to-guides/clusters/troubleshooting.mdx b/docs/how-to-guides/clusters/troubleshooting.mdx
index d95786d..5646f16 100644
--- a/docs/how-to-guides/clusters/troubleshooting.mdx
+++ b/docs/how-to-guides/clusters/troubleshooting.mdx
@@ -87,7 +87,7 @@ Create an SSH key pair in the target AWS region through the EC2 console. Vantage
- **Cloud clusters:** Verify the minimum size is set to at least 1 if you expect nodes to always be present. Autoscaling scales to zero when `min_size = 0`.
- **Slurm on Kubernetes:** Ensure the parent K8s cluster has sufficient capacity and the autoscaler is enabled. The AWS autoscaler uses EC2 Fleet to provision instances.
-- **On-premises clusters:** Nodes must be registered manually on your infrastructure. Install the Vantage connector on each node. See [On-Premises clusters](/reference/clusters/on-premises) and use the Manual tab for details.
+- **On-premises clusters:** Nodes must be registered manually on your infrastructure. Install the Vantage connector on each node. See [On-Premises clusters](/how-to-guides/clusters/on-premises) and use the Manual tab for details.
## Cluster not appearing in the list
diff --git a/docs/reference/clusters/federations/index.md b/docs/reference/clusters/federations/index.md
index 7697cea..ec221b7 100644
--- a/docs/reference/clusters/federations/index.md
+++ b/docs/reference/clusters/federations/index.md
@@ -7,16 +7,11 @@ description: Link multiple clusters together for distributed workloads across re
Federations link multiple Vantage clusters so workloads can span across regions, providers, and infrastructure boundaries. A federation acts as a single logical compute pool, submit a job to the federation and Vantage routes it to an available cluster.
-[Get started](/how-to-guides/clusters/federations/get-started/) · [Concepts](/explanation/federations)
-
## What you'll find inside
-- **[How-to guides](/how-to-guides/clusters/federations/manage):** Task-oriented recipes for creating and managing federations.
-- **[Tutorials](/how-to-guides/clusters/federations/tutorials):** Walk through federation setup end-to-end.
- **[Reference](/reference/clusters/federations/reference):** CLI commands, configuration fields, and API schema.
-## Next steps
+## See also
-- [Quickstart](/how-to-guides/clusters/federations/get-started/): Create a federation from the CLI in under two minutes
-- [Concepts](/explanation/federations): How federations route workloads across clusters
-- [CLI reference](/reference/developer-tools/cli/commands): Full federation command reference
+- [Federation concepts](/explanation/federations)
+- [Manage federations how-to](/how-to-guides/clusters/federations/manage)
diff --git a/docs/reference/clusters/index.md b/docs/reference/clusters/index.md
index 2217184..3516f55 100644
--- a/docs/reference/clusters/index.md
+++ b/docs/reference/clusters/index.md
@@ -14,17 +14,6 @@ Vantage supports three cluster types:
- **[Slurm on Kubernetes](/reference/clusters/kubernetes#slurm-on-kubernetes):** A Slurm scheduler deployed inside an existing Kubernetes cluster. Gives you HPC scheduling on cloud-native, auto-scaled infrastructure without managing a separate Slurm controller fleet.
- **[On-Premises](/reference/clusters/on-premises):** Connect your own infrastructure using Ansible, Terraform, manual setup, Multipass, or Juju (Charmed HPC). Manual and automated (Ansible/Terraform) clusters support both Slurm and Kubernetes. Multipass and Juju provide local Slurm environments for development and testing.
-## Getting started
-
-Start with the [quickstart](/how-to-guides/clusters/get-started) to create your first cluster in minutes, then choose a guide based on your workload:
-
-| If you want... | Start here |
-|---|---|
-| Batch HPC jobs with Slurm | [Slurm overview](/reference/clusters/slurm) |
-| Interactive ML development | [Kubernetes overview](/reference/clusters/kubernetes) |
-| HPC on cloud-native infra | [Slurm on Kubernetes](/reference/clusters/kubernetes#slurm-on-kubernetes) |
-| On-premises HPC without cloud | [On-Premises overview](/reference/clusters/on-premises) |
-
## Supported providers
Vantage provisions clusters on five infrastructure types:
@@ -54,3 +43,8 @@ See [On-Premises clusters](/reference/clusters/on-premises) for setup guides.
- **Cloud accounts** are the credential bindings that let Vantage provision infrastructure. One account backs multiple clusters. See [Compute Providers](/reference/settings/compute-providers).
- **Compute profiles** define the shape of compute (GPU type, count, instance class) and are shared across Workbench sessions, training jobs, and endpoints.
- **Workspaces** provide quota, RBAC, and cost isolation. A cluster can be shared across workspaces.
+
+## See also
+
+- [Clusters concepts](/explanation/clusters)
+- [Create a cluster how-to](/how-to-guides/clusters/get-started)
diff --git a/docs/reference/clusters/kubernetes/index.mdx b/docs/reference/clusters/kubernetes/index.mdx
index d19e7c8..a027527 100644
--- a/docs/reference/clusters/kubernetes/index.mdx
+++ b/docs/reference/clusters/kubernetes/index.mdx
@@ -34,7 +34,7 @@ When you create a Kubernetes cluster, Vantage:
| Custom networking | VPC, subnet, security group | No | No |
| Slurm on K8s supported | Yes | No | No |
-:::note Multipass and Juju on-premises clusters only support Slurm, not Kubernetes. For on-premises Kubernetes, see [On-Premises clusters](/reference/clusters/on-premises) and choose the Kubernetes tab.:::
+:::note Multipass and Juju on-premises clusters only support Slurm, not Kubernetes. For on-premises Kubernetes, see [On-Premises clusters](/how-to-guides/clusters/on-premises) and choose the Kubernetes tab.:::
## Slurm on Kubernetes
@@ -52,4 +52,4 @@ For details, see [creating a Slurm-on-Kubernetes cluster](/how-to-guides/cluster
- [Compute pools](/reference/clusters/kubernetes/node-groups): Compute pools and autoscaling
- [Integrations](/reference/clusters/kubernetes/integrations): JupyterHub, Grafana, Ray, MLflow
- [Reference](/reference/clusters/kubernetes/reference): Fields, limits, error codes
-- [On-Premises clusters](/reference/clusters/on-premises): Connect your own Kubernetes infrastructure
+- [On-Premises clusters](/how-to-guides/clusters/on-premises): Connect your own Kubernetes infrastructure
diff --git a/docs/reference/clusters/on-premises.mdx b/docs/reference/clusters/on-premises.mdx
index 08cc502..faa239d 100644
--- a/docs/reference/clusters/on-premises.mdx
+++ b/docs/reference/clusters/on-premises.mdx
@@ -1,734 +1,26 @@
---
title: On-Premises clusters
-description: Connect your own infrastructure to Vantage using Ansible, Terraform, Kubernetes, Juju, Multipass, or manual setup.
+description: Reference for on-premises cluster connection methods supported by Vantage.
---
# On-Premises clusters
On-premises clusters run on infrastructure you control, bare-metal servers, local VMs, or LXD containers. Vantage supports multiple methods for connecting your infrastructure, each suited to a different use case and level of automation.
-
+## Supported methods
-
-
-
Ansible
-
+| Method | Scheduler | Automation | Best for |
+|---|---|---|---|
+| Ansible | Slurm | Ansible role | Repeatable, automated deployments of existing Slurm clusters |
+| Terraform | Slurm | Terraform module | Infrastructure-as-code deployments of existing Slurm clusters |
+| Kubernetes | Kubernetes | Manual connector | Connecting an existing Kubernetes cluster to Vantage |
+| Juju (Charmed HPC) | Slurm | Juju charms | Multi-node Slurm environment in LXD containers on a single host |
+| Multipass | Slurm | v8x CLI | Single-node Slurm in a local VM for development and testing |
+| Manual | Slurm, Kubernetes | Manual connector | Full control over installation on existing servers or bare metal |
-
-
-
Terraform
-
+For step-by-step setup instructions for each method, see the how-to guide.
-
-
-
Kubernetes
-
+## See also
-
-
-
Juju
-
-
-
-
-
Multipass
-
-
-
-
-
Manual
-
-
-
-
-## Prerequisites
-
-All on-premises methods require:
-
-- A Vantage account and organization ([Sign up](/tutorial))
-- A configured [On-Premises or LXD Cloud Account](/reference/settings/compute-providers/on-premises)
-- Outbound HTTPS access (port 443) from your infrastructure to Vantage servers
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-
-
-
-
-
-
-
-
-
-
-Use the [vantage-agents Ansible role](https://github.com/vantagecompute/ansible-role-vantage_agents) to automate connecting your Slurm cluster to Vantage. The role installs and configures both `vantage-agent` and `jobbergate-agent` on your controller node.
-
-### Prerequisites
-
-- An existing Slurm cluster with SSH access to the controller node
-- Ansible 2.9+ installed on your workstation
-- OIDC credentials from your Vantage cluster (client ID and client secret)
-
-### 1. Create a Slurm cluster in Vantage
-
-1. **Open Clusters:** Click **Clusters** in the left sidebar, then click **Slurm** in the cluster type navigation, then click Prepare Cluster.
-
-1. **Configure the cluster:**
- - Enter a **Cluster Name** (max 27 characters, must be unique).
- - Select your **On-Premises** or **LXD** cloud account.
-
-1. **Submit:** Click Create Cluster. Note the **OIDC Client ID** and **OIDC Client Secret** from the cluster detail page, you will need these in the next step.
-
-### 2. Install the Ansible role
-
-```bash
-ansible-galaxy install git+https://github.com/vantagecompute/ansible-role-vantage_agents.git,vantage_agents
-```
-
-### 3. Create a playbook
-
-```yaml
-- hosts: util_node
- become: true
- vars:
- oidc_client_id: ""
- oidc_client_secret: ""
- cluster_name: ""
- install_type: "snap" # or "pypi"
- roles:
- - role: vantage_agents
-```
-
-### 4. Run the playbook
-
-```bash
-ansible-playbook -i your_inventory your_playbook.yml
-```
-
-### 5. Verify the connection
-
-Once the playbook completes:
-
-- The cluster transitions from `preparing` to `ready` in the Vantage UI
-- Nodes appear in the cluster detail page as they register
-- You can submit jobs and launch notebooks immediately
-
-:::tip
-The Ansible role supports both Snap (default) and PyPI installation methods. Set `install_type: "pypi"` in your playbook vars to use Python virtual environments with systemd services instead of Snap packages.
-:::
-
-### Next steps
-
-- [Manage a Slurm cluster](/reference/clusters/slurm/manage)
-- [Slurm partitions](/reference/clusters/slurm/partitions)
-- [ansible-role-vantage_agents on GitHub](https://github.com/vantagecompute/ansible-role-vantage_agents)
-
-
-
-
-Use the [terraform-vantage-agents module](https://github.com/vantagecompute/terraform-vantage-agents) to automate connecting your Slurm cluster to Vantage. The module SSH-es into your controller node and installs both `vantage-agent` and `jobbergate-agent`.
-
-### Prerequisites
-
-- An existing Slurm cluster with SSH access to the controller node
-- Terraform 1.0+ installed on your workstation
-- OIDC credentials from your Vantage cluster (client ID and client secret)
-
-### 1. Create a Slurm cluster in Vantage
-
-1. **Open Clusters:** Click **Clusters** in the left sidebar, then click **Slurm** in the cluster type navigation, then click Prepare Cluster.
-
-1. **Configure the cluster:**
- - Enter a **Cluster Name** (max 27 characters, must be unique).
- - Select your **On-Premises** or **LXD** cloud account.
-
-1. **Submit:** Click Create Cluster. Note the **OIDC Client ID** and **OIDC Client Secret** from the cluster detail page, you will need these in the next step.
-
-### 2. Configure the Terraform module
-
-```hcl
-module "vantage_agents" {
- source = "github.com/vantagecompute/terraform-vantage-agents"
-
- ssh_user = var.ssh_user
- ssh_private_key = file(var.ssh_private_key)
- host = var.host
-
- oidc_client_id = var.oidc_client_id
- oidc_client_secret = var.oidc_client_secret
- cluster_name = var.cluster_name
-
- # Optional: set to "pypi" for Python venv + systemd instead of Snap
- # install_type = "pypi"
-}
-```
-
-### 3. Apply the configuration
-
-```bash
-terraform init
-terraform apply
-```
-
-### 4. Verify the connection
-
-Once Terraform completes:
-
-- The cluster transitions from `preparing` to `ready` in the Vantage UI
-- Nodes appear in the cluster detail page as they register
-- You can submit jobs and launch notebooks immediately
-
-:::tip
-The Terraform module supports both Snap (default) and PyPI installation methods. Set `install_type = "pypi"` to use Python virtual environments with systemd services instead of Snap packages.
-:::
-
-### Next steps
-
-- [Manage a Slurm cluster](/reference/clusters/slurm/manage)
-- [Slurm partitions](/reference/clusters/slurm/partitions)
-- [terraform-vantage-agents on GitHub](https://github.com/vantagecompute/terraform-vantage-agents)
-
-
-
-
-Connect an existing Kubernetes cluster to Vantage. Vantage does not provision cloud resources for on-premises K8s, you provide the compute infrastructure.
-
-### Prerequisites
-
-- An existing Kubernetes cluster with a reachable API server
-- A configured On-Premises or LXD cloud account in Vantage
-- Outbound HTTPS access (port 443) from your cluster to Vantage servers
-
-### 1. Create a Kubernetes cluster in Vantage
-
-1. **Open Clusters:** Click **Clusters** in the left sidebar (the **Kubernetes** view is shown by default), then click Prepare Cluster.
-
-1. **Configure:**
- - Enter a **Cluster Name**.
- - Select your **On-Premises** or **LXD** cloud account.
-
-1. **Submit:** Click Create Cluster. The modal closes and you are redirected to the cluster view.
-
-### 2. Connect your cluster
-
-After creating the cluster, the cluster detail page shows that the connection is not yet established and provides instructions for connecting your infrastructure.
-
-Follow the on-screen instructions to install the Vantage connector on your cluster. The connector only needs outbound HTTPS access to Vantage servers (port 443). If your cluster is behind a firewall, ensure outbound connectivity is not blocked.
-
-Once the connector is active:
-
-- The cluster transitions from `preparing` to `ready`
-- Nodes appear in the cluster detail page as they register
-- You can launch notebooks and deploy workloads immediately
-
-:::note
-Multipass and Juju on-premises clusters only support Slurm, not Kubernetes. For Kubernetes on your own hardware, use this method.
-:::
-
-### Troubleshooting
-
-#### Cluster stays in "preparing"
-
-- Verify the connector was installed and is running on your control plane node.
-- Check that port 443 outbound is not blocked by a firewall.
-- Confirm the cloud account credentials are valid.
-
-#### Nodes not appearing
-
-- Install the connector on each worker node, not just the control plane.
-- Check that each node can reach Vantage servers over HTTPS.
-
-### Next steps
-
-- [Manage a Kubernetes cluster](/reference/clusters/kubernetes/manage)
-- [Kubernetes compute pools](/reference/clusters/kubernetes/node-groups)
-
-
-
-
-Deploy a production-like Slurm cluster on your local machine using Juju charms and LXD containers. Charmed HPC provides a full HPC stack, controller, compute, database, REST API, login node, and Vantage integration, all running inside LXD containers on a single host.
-
-### Prerequisites
-
-- Ubuntu 22.04 or 24.04 (host machine)
-- LXD installed and initialised (`lxd init`)
-- Juju snap installed
-- Internet access to download charms and container images
-
-### 1. Bootstrap a Juju controller
-
-```bash
-juju bootstrap lxd
-```
-
-This creates a controller named `lxd-default` inside an LXD container. It manages all models and workloads.
-
-### 2. Add a model for your Slurm cluster
-
-```bash
-juju add-model myslurmcluster
-```
-
-Models are logical environments. Name yours whatever you like, `myslurmcluster` is used throughout this guide.
-
-### 3. Deploy the required charms
-
-Use Ubuntu 24.04 as the base for Slurm charms. MySQL uses Ubuntu 22.04 (charm default).
-
-```bash
-juju deploy slurmctld --base ubuntu@24.04 --channel 25.11/edge
-juju deploy slurmdbd --base ubuntu@24.04 --channel 25.11/edge
-juju deploy mysql --channel 8.0/stable
-juju deploy slurmrestd --base ubuntu@24.04 --channel 25.11/edge
-juju deploy slurmd --base ubuntu@24.04 --channel 25.11/edge
-juju deploy sackd --base ubuntu@24.04 --channel 25.11/edge
-juju deploy jobbergate-agent --channel latest/edge --base ubuntu@24.04
-juju deploy vantage-agent --channel latest/edge --base ubuntu@24.04
-```
-
-### 4. Add relations (integrations)
-
-```bash
-juju relate slurmctld slurmdbd
-juju relate slurmctld slurmrestd
-juju relate slurmctld slurmd
-juju relate slurmdbd mysql
-juju relate sackd slurmctld
-juju relate jobbergate-agent sackd
-juju relate vantage-agent sackd
-```
-
-These connections enable:
-
-- Accounting and configuration sharing
-- REST API access
-- Compute node registration
-- Vantage integration with Slurm
-
-### 5. Configure the charms
-
-#### Compute node initial state
-
-Set slurmd nodes to start in `idle` (ready to run jobs) or `down` (manual resume). Use lowercase only:
-
-```bash
-juju config slurmd default-node-state=idle
-```
-
-#### OIDC credentials (for Vantage integration)
-
-Replace the example values with your real OIDC client ID and secret.
-
-```bash
-juju config jobbergate-agent jobbergate-agent-oidc-client-id=your-client-id
-juju config jobbergate-agent jobbergate-agent-oidc-client-secret=your-client-secret
-juju config vantage-agent vantage-agent-oidc-client-id=your-client-id
-juju config vantage-agent vantage-agent-oidc-client-secret=your-client-secret
-```
-
-#### Vantage cluster name
-
-```bash
-juju config vantage-agent vantage-agent-cluster-name=myslurmcluster
-```
-
-### 6. Monitor deployment
-
-```bash
-juju status --watch 1s
-```
-
-Wait until all applications show `active` and all units are `idle`.
-
-Expected status:
-
-| Application | Expected status |
-|---|---|
-| `slurmctld`, `slurmdbd`, `mysql`, `slurmd`, `slurmrestd`, `sackd` | `active` |
-| `jobbergate-agent`, `vantage-agent` | `active` (once OIDC and cluster name are set) |
-
-### 7. Verify the Slurm cluster
-
-SSH into the controller unit (machine 0):
-
-```bash
-juju ssh 0
-```
-
-Check the partition and nodes:
-
-```bash
-sinfo
-```
-
-You should see the `slurmd` partition and at least one node in `idle` state.
-
-If the node is `down`, resume it:
-
-```bash
-sudo scontrol update nodename=slurmd-0 state=resume
-```
-
-Submit a test job:
-
-```bash
-sbatch -p slurmd --wrap="sleep 10; hostname"
-squeue
-```
-
-After a few seconds, `squeue` should show the job running (`R`) then disappear. Check the output:
-
-```bash
-cat slurm-*.out
-```
-
-Exit the controller:
-
-```bash
-exit
-```
-
-### Troubleshooting
-
-#### Deployment failures
-
-```bash
-juju status
-juju debug-log --include slurmctld
-```
-
-#### Container issues
-
-```bash
-lxc list
-lxc logs
-lxc restart
-```
-
-#### Network connectivity
-
-```bash
-lxc network show lxdbr0
-lxc exec -- ping google.com
-```
-
-#### Slurm services not running
-
-```bash
-juju ssh slurmctld/0
-sudo systemctl status slurmctld
-sudo systemctl status slurmdbd
-sudo systemctl restart slurmctld slurmdbd
-sudo journalctl -u slurmctld -f
-```
-
-### Next steps
-
-- [Submit jobs to your cluster](/reference/jobs)
-- Create a Multipass cluster using the Multipass tab below for simpler single-node setups
-- Connect manually using the Manual tab below for production on-premises deployments
-
-
-
-
-Deploy a single-node Slurm cluster in a Multipass VM on your local machine. Multipass provides lightweight Ubuntu VMs managed through a simple CLI, ideal for development, testing, and learning Vantage without cloud infrastructure.
-
-Multipass clusters are created and managed entirely through the terminal using the v8x.
-
-:::tip When to use Multipass
-
-Use Multipass when you want to:
-
-- Try Vantage without cloud infrastructure
-- Develop and test Slurm job scripts locally
-- Learn HPC workflows on your laptop
-
-For a multi-node HPC environment, use the Juju tab below instead. For connecting existing production hardware, use the Manual tab below.
-:::
-
-### Prerequisites
-
-- A Vantage account and organization ([Sign up](/tutorial))
-- A Linux, macOS, or Windows machine with at least 8 GB RAM and 20 GB disk space
-- [Snap](https://snapcraft.io/docs/installing-snapd) package manager (Linux) or Homebrew (macOS)
-
-### 1. Install v8x
-
-```bash
-uvx v8x
-```
-
-Verify the installation:
-
-```bash
-uvx v8x version
-```
-
-Log in to your Vantage account:
-
-```bash
-uvx v8x login
-```
-
-### 2. Install Multipass
-
-```bash
-# Linux (via snap)
-sudo snap install multipass
-
-# macOS (via Homebrew)
-brew install --cask multipass
-
-# Windows, download the installer from https://multipass.run/install
-```
-
-Verify the installation:
-
-```bash
-multipass --version
-```
-
-### 3. Deploy the cluster
-
-Deploy a single-node Slurm cluster:
-
-```bash
-uvx v8x app deploy slurm-multipass-localhost
-```
-
-Monitor the deployment progress:
-
-```bash
-uvx v8x app status slurm-multipass-localhost
-```
-
-Wait until the VM is running and Slurm services are ready:
-
-```bash
-multipass list
-```
-
-The output should show the VM in a `Running` state.
-
-#### Custom resources
-
-By default, the cluster uses 4 CPUs, 8 GB RAM, and 50 GB disk. Customize resources during deployment:
-
-```bash
-uvx v8x app deploy slurm-multipass-localhost \
- --cpus=4 \
- --memory=8G \
- --disk=50G
-```
-
-### 4. Access the cluster
-
-Connect to the VM:
-
-```bash
-multipass shell slurm-node
-```
-
-Or use SSH:
-
-```bash
-ssh ubuntu@$(multipass info slurm-node --format json | jq -r '.info."slurm-node".ipv4[0]')
-```
-
-### 5. Verify Slurm
-
-Once connected to the VM, verify that Slurm is running:
-
-```bash
-sinfo
-squeue
-```
-
-Submit a test job:
-
-```bash
-srun --nodes=1 --ntasks=1 hostname
-```
-
-Or submit a batch job:
-
-```bash
-sbatch <
-
-
-Connect your existing Slurm or Kubernetes cluster to Vantage by manually installing the Vantage connector on your infrastructure. This method gives you full control over the installation process and works with any Linux server that meets the prerequisites.
-
-### Prerequisites
-
-- A Vantage account and organization ([Sign up](/tutorial))
-- A configured [On-Premises or LXD Cloud Account](/reference/settings/compute-providers/on-premises)
-- Outbound HTTPS access (port 443) from your infrastructure to Vantage servers
-- SSH access to your cluster nodes
-
-### Create a Slurm cluster
-
-1. **Open Clusters:** Click **Clusters** in the left sidebar, then click **Slurm** in the cluster type navigation, then click Prepare Cluster.
-
-1. **Configure the cluster:**
- - Enter a **Cluster Name** (max 27 characters, must be unique).
- - Select your **On-Premises** or **LXD** cloud account.
-
-1. **Submit:** Click Create Cluster. A success toast confirms the cluster was created. The modal closes and you are redirected to the cluster view.
-
-### Create a Kubernetes cluster
-
-1. **Open Clusters:** Click **Clusters** in the left sidebar (the **Kubernetes** view is shown by default), then click Prepare Cluster.
-
-1. **Configure:**
- - Enter a **Cluster Name**.
- - Select your **On-Premises** or **LXD** cloud account.
-
-1. **Submit:** Click Create Cluster. The modal closes and you are redirected to the cluster view.
-
-### Connect your cluster
-
-After creating the cluster, the cluster detail page shows a message that the connection is not yet established and provides a link to installation instructions. Follow those instructions to install the Vantage connector on your cluster node.
-
-The connector only needs outbound HTTPS access to Vantage servers (port 443). If your cluster is behind a firewall, ensure outbound connectivity is not blocked.
-
-Once the connector is active:
-
-- The cluster transitions from `preparing` to `ready`
-- Nodes appear in the cluster detail page as they register
-- You can submit jobs and launch notebooks immediately
-
-:::tip
-On-premises clusters report their location as configured by your admin. Partitions and compute pools are configured post-creation from the cluster detail page.
-:::
-
-### Troubleshooting
-
-#### Cluster stays in "preparing"
-
-- Verify the connector was installed and is running on your head node.
-- Check that port 443 outbound is not blocked by a firewall.
-- Confirm the cloud account credentials are valid.
-
-#### Nodes not appearing
-
-- Install the connector on each compute node, not just the head node.
-- Check that each node can reach Vantage servers over HTTPS.
-
-### Next steps
-
-- [Manage a Slurm cluster](/reference/clusters/slurm/manage)
-- [Manage a Kubernetes cluster](/reference/clusters/kubernetes/manage)
-- [Slurm partitions](/reference/clusters/slurm/partitions)
-- [Kubernetes compute pools](/reference/clusters/kubernetes/node-groups)
-
-
-
-
-## Which method should I use?
-
-- **Ansible:** You manage your Slurm infrastructure with Ansible and want automated, repeatable deployments.
-- **Terraform:** You manage your Slurm infrastructure with Terraform and want infrastructure-as-code deployments.
-- **Kubernetes:** You have an existing Kubernetes cluster and want to connect it to Vantage.
-- **Juju (Charmed HPC):** You want a multi-node Slurm environment that simulates a production HPC cluster, running locally in LXD containers.
-- **Multipass:** You want a quick, single-node Slurm environment on your laptop for development and testing.
-- **Manual:** You have existing servers or bare-metal hardware and want full control over the installation process. Supports both Slurm and Kubernetes.
-
-:::tip
-Ansible, Terraform, and Juju clusters are configured through their respective tooling. Manual clusters are configured through the Vantage web UI. Multipass clusters are created through the v8x.
-:::
\ No newline at end of file
+- [On-premises clusters how-to](/how-to-guides/clusters/on-premises)
+- [Clusters concepts](/explanation/clusters)
\ No newline at end of file
diff --git a/docs/reference/clusters/slurm/index.mdx b/docs/reference/clusters/slurm/index.mdx
index 5f43cf8..21ce2f1 100644
--- a/docs/reference/clusters/slurm/index.mdx
+++ b/docs/reference/clusters/slurm/index.mdx
@@ -32,7 +32,7 @@ Provisioning is asynchronous. The cluster enters `preparing` status immediately
| SSH key required | Yes (EC2 key pair name) | No | No |
| Custom networking | VPC, subnet, security group | No | No |
-:::tip On-premises clusters can be created through the web UI (manual), Ansible, Terraform, or the Vantage CLI (Multipass and Juju). See [On-Premises clusters](/reference/clusters/on-premises) for details.:::
+:::tip On-premises clusters can be created through the web UI (manual), Ansible, Terraform, or the Vantage CLI (Multipass and Juju). See [On-Premises clusters](/how-to-guides/clusters/on-premises) for details.:::
## Next steps
@@ -40,4 +40,4 @@ Provisioning is asynchronous. The cluster enters `preparing` status immediately
- [Manage a Slurm cluster](/reference/clusters/slurm/manage): Status lifecycle, detail page, monitoring
- [Partitions](/reference/clusters/slurm/partitions): Job queues and node pools
- [Reference](/reference/clusters/slurm/reference): Fields, limits, error codes
-- [On-Premises clusters](/reference/clusters/on-premises): Ansible, Terraform, manual, Multipass, and Juju setup
+- [On-Premises clusters](/how-to-guides/clusters/on-premises): Ansible, Terraform, manual, Multipass, and Juju setup
diff --git a/docs/reference/developer-tools/cli/index.md b/docs/reference/developer-tools/cli/index.md
index 54f90c7..1825a2d 100644
--- a/docs/reference/developer-tools/cli/index.md
+++ b/docs/reference/developer-tools/cli/index.md
@@ -71,5 +71,5 @@ uvx v8x cluster create my-slurm-microk8s-cluster \
- [Commands Reference](/reference/developer-tools/cli/commands) – Complete Command Reference
- [Private Installation Configuration](/how-to-guides/developer-tools/cli/private-vantage-installation) – Partner Vantage Deployment CLI Profile Configuration
- [Usage Examples](/how-to-guides/developer-tools/cli/usage) – Practical Command Patterns
-- [Architecture](/explanation/cli-architecture) – Internals & Module Layout
+- [Architecture](/reference/developer-tools/cli/architecture) – Internals & Module Layout
- [Troubleshooting](/how-to-guides/developer-tools/cli/troubleshooting) – Common Issues and Solutions
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 8bcdbc6..e151fa9 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -7,18 +7,32 @@ description: Lookup documentation for Vantage concepts, configuration, and APIs.
Reference docs are for looking up details: configuration fields, supported options, lifecycle behavior, shortcuts, and API surfaces.
-## Platform reference
+## By area
-- [Clusters](/reference/clusters)
-- [Jobs](/reference/jobs)
-- [Workbench](/reference/workbench)
-- [Storage](/reference/storage)
-- [Licenses](/reference/licenses)
-- [Teams](/reference/teams)
-- [Settings](/reference/settings/compute-providers)
+Lookup material for each product area, organized the same way as the how-to guides.
+
+- [Clusters](/reference/clusters) - cluster types, providers, federations
+- [Jobs](/reference/jobs) - scripts, templates, submissions, catalog
+- [Workbench](/reference/workbench) - sessions, training, pipelines, endpoints
+- [Storage](/reference/storage) - PVCs, NFS, CephFS
+- [Licenses](/reference/licenses) - hosting models, supported servers
+- [Teams](/reference/teams) - membership, roles, ownership
+- [Users & permissions](/reference/settings/iam) - IAM and permission groups
+- [Cloud accounts](/reference/settings/compute-providers) - providers and partners
+
+## Developer tools & internals
+
+Cross-cutting developer material that doesn't belong to a single area.
+
+- [Vantage CLI](/reference/developer-tools/cli) - command reference
+- [Vantage SDK](/reference/developer-tools/sdk) - SDK API reference
+- [Vantage API](/reference/developer-tools/api) - REST, OpenAPI, interactive docs
+- [CLI architecture](/reference/developer-tools/cli/architecture) - module map, auth flow, internals
## Frequently used reference pages
+Quick links to the most-visited lookup pages.
+
- [Workbench keyboard shortcuts](/reference/workbench/shortcuts)
- [Session configuration reference](/reference/workbench/sessions/reference)
- [Training job configuration reference](/reference/workbench/training-jobs/reference)
@@ -26,11 +40,4 @@ Reference docs are for looking up details: configuration fields, supported optio
- [Slurm configuration reference](/reference/clusters/slurm/reference)
- [Kubernetes configuration reference](/reference/clusters/kubernetes/reference)
- [License configuration reference](/reference/licenses/reference)
-- [IAM reference](/reference/settings/iam/reference)
-
-## Developer tools reference
-
-- [Vantage CLI](/reference/developer-tools/cli)
-- [Vantage SDK](/reference/developer-tools/sdk)
-- [Vantage API](/reference/developer-tools/api)
-- [Legacy CLI deployment application docs](/reference/developer-tools/cli)
+- [IAM configuration reference](/reference/settings/iam/reference)
diff --git a/docs/reference/jobs/index.mdx b/docs/reference/jobs/index.mdx
index 5055836..bae1560 100644
--- a/docs/reference/jobs/index.mdx
+++ b/docs/reference/jobs/index.mdx
@@ -7,8 +7,6 @@ description: Job management for HPC workloads, scripts, templates, submissions,
Vantage Jobs is where you define, submit, and track computational work on your clusters.
-[Get started](/how-to-guides/jobs/get-started) · [Concepts](/explanation/jobs)
-
## What you'll find inside
- **[Scripts](/reference/jobs/scripts):** Slurm batch scripts stored in Vantage's script library. Built-in editor, support files, clone/archive/delete lifecycle. Create from scratch or render from a template.
@@ -16,10 +14,7 @@ Vantage Jobs is where you define, submit, and track computational work on your c
- **[Submissions](/reference/jobs/submissions):** Workloads dispatched to a cluster. Real-time status tracking, resource metrics (CPU, memory, GPU, disk I/O), log viewing, and lifecycle actions (re-submit, edit, delete).
- **[Catalog](/reference/jobs/catalog):** Pre-built job scripts that work out of the box on Vantage cloud clusters. One-click import to your script library.
-## Next steps
+## See also
-- [Quickstart](/how-to-guides/jobs/get-started): submit your first job in under five minutes
-- [Concepts](/explanation/jobs): understand the key mental models
-- [Scripts](/reference/jobs/scripts): create and manage job scripts
-- [Templates](/reference/jobs/templates): build reusable script blueprints
-- [Submissions](/reference/jobs/submissions): submit and monitor workloads
+- [Jobs concepts](/explanation/jobs)
+- [Jobs how-to](/how-to-guides/jobs/get-started)
diff --git a/docs/reference/licenses/index.md b/docs/reference/licenses/index.md
index 9ee9532..629a74d 100644
--- a/docs/reference/licenses/index.md
+++ b/docs/reference/licenses/index.md
@@ -7,8 +7,6 @@ description: Connect commercial software license servers so Vantage clusters can
Licenses is where you connect and manage your commercial software license servers, FlexLM, RLM, LMX, and others, so Vantage clusters can check out licenses when jobs need them.
-[Get started](/how-to-guides/licenses/) · [Concepts](/explanation/licenses)
-
## Hosting models
| Model | Who manages it | Best for |
@@ -25,8 +23,7 @@ Licenses is where you connect and manage your commercial software license server
- **DSLS:** Dassault Systemes license server management.
- **OLicense:** Enterprise license management with advanced analytics.
-## Next steps
+## See also
-- [Quickstart](/how-to-guides/licenses/): Connect a license server in under five minutes
-- [Concepts](/explanation/licenses): How licenses integrate with jobs
-- [How-to guides](/how-to-guides/licenses): Step-by-step setup for each license server type
+- [Licenses concepts](/explanation/licenses)
+- [Licenses how-to](/how-to-guides/licenses/)
diff --git a/docs/reference/settings/compute-providers/index.md b/docs/reference/settings/compute-providers/index.md
index e518377..ebd4a38 100644
--- a/docs/reference/settings/compute-providers/index.md
+++ b/docs/reference/settings/compute-providers/index.md
@@ -7,15 +7,13 @@ description: Connect Vantage to AWS, Azure, GCP, on-premises, and partner comput
Compute Providers is where you connect external compute resources so Vantage can provision clusters on your behalf.
-[Get started](/how-to-guides/cloud-accounts/get-started) · [Concepts](/explanation/compute-providers)
-
## What you'll find inside
- **[Public clouds](/reference/settings/compute-providers/public-clouds):** AWS, Azure, and GCP accounts. Elastic capacity, spot pricing, global regions.
- **[On-premises](/reference/settings/compute-providers/on-premises):** Your own hardware or private cloud, connected via LXD or direct on-prem integration.
- **[Vantage Partners](/reference/settings/compute-providers/vantage-partners):** Pre-integrated managed providers: atNorth, BuzzHPC, and Responsible Compute.
-## Next steps
+## See also
-- [Quickstart](/how-to-guides/cloud-accounts/get-started): Add your first cloud account in under five minutes
-- [Concepts](/explanation/compute-providers): How cloud accounts work
+- [Compute providers concepts](/explanation/compute-providers)
+- [Cloud accounts how-to](/how-to-guides/cloud-accounts/get-started)
diff --git a/docs/reference/settings/compute-providers/on-premises.md b/docs/reference/settings/compute-providers/on-premises.md
index bbce0f5..eefa904 100644
--- a/docs/reference/settings/compute-providers/on-premises.md
+++ b/docs/reference/settings/compute-providers/on-premises.md
@@ -39,7 +39,7 @@ Multipass provides lightweight Ubuntu VMs for local development and testing. Use
1. Install Multipass: `sudo snap install multipass`
2. Deploy a Slurm cluster using the Vantage CLI: `uvx v8x app deploy slurm-multipass-localhost`
-See [On-Premises clusters](/reference/clusters/on-premises) and choose the Multipass tab for the full setup guide.
+See [On-Premises clusters](/how-to-guides/clusters/on-premises) and choose the Multipass tab for the full setup guide.
## Juju (Charmed HPC)
@@ -48,9 +48,9 @@ Juju deploys multi-node Slurm clusters using charms on LXD containers. Use it to
1. Install Juju: `sudo snap install juju --channel 3/stable`
2. Bootstrap a Juju controller: `juju bootstrap lxd`
3. Add a model: `juju add-model myslurmcluster`
-4. Deploy the Slurm and Vantage charms: see [On-Premises clusters](/reference/clusters/on-premises) and choose the Juju tab for the full charm list and configuration steps.
+4. Deploy the Slurm and Vantage charms: see [On-Premises clusters](/how-to-guides/clusters/on-premises) and choose the Juju tab for the full charm list and configuration steps.
-See [On-Premises clusters](/reference/clusters/on-premises) and choose the Juju tab for the full setup guide.
+See [On-Premises clusters](/how-to-guides/clusters/on-premises) and choose the Juju tab for the full setup guide.
:::tip
On-premises accounts carry no cloud spend per se, but your hardware runs continuously. Idle nodes still consume power, cooling, and rack space. Plan capacity around your actual workload schedule.
diff --git a/docs/reference/settings/iam/index.md b/docs/reference/settings/iam/index.md
index 8e7dfc7..1c718b0 100644
--- a/docs/reference/settings/iam/index.md
+++ b/docs/reference/settings/iam/index.md
@@ -7,15 +7,13 @@ description: Manage users, permission groups, and authentication across your Van
IAM is where you manage users, permission groups, and authentication for your Vantage organization. It covers everything from inviting users to configuring SSO.
-[Get started](/how-to-guides/iam/get-started) · [Concepts](/explanation/iam)
-
## What you'll find inside
- **Users:** Everyone with access to your organization. Each user has one or more permission groups that control what they can see and do.
- **Permission groups:** Named bundles of permissions: admin, cluster admin, jobs admin, and more. Assign groups to users to grant access.
- **Authentication:** OAuth (Google, GitHub), federated identity (OIDC/SAML), and API keys for programmatic access.
-## Next steps
+## See also
-- [Quickstart](/how-to-guides/iam/get-started): Invite a user and assign permissions in under two minutes
-- [Concepts](/explanation/iam): Permission groups, roles, and authentication explained
+- [IAM concepts](/explanation/iam)
+- [IAM how-to](/how-to-guides/iam/get-started)
diff --git a/docs/reference/storage.md b/docs/reference/storage.md
index fa71d65..9e6a340 100644
--- a/docs/reference/storage.md
+++ b/docs/reference/storage.md
@@ -7,16 +7,13 @@ description: Attach persistent volumes, NFS shares, and CephFS mounts to your Ku
Storage is where you create and manage the persistent volumes, NFS shares, and CephFS mounts that your Kubernetes workloads and Workbench sessions can read from and write to.
-[Get started](/how-to-guides/storage/) · [Concepts](/explanation/storage)
-
## What you'll find inside
- **PVCs:** Persistent Volume Claims backed by your cluster's storage classes. Request the capacity and access mode you need; the cluster provisions the volume automatically.
- **NFS:** Mount an external NFS server or expose an existing PVC as an NFS share accessible across namespaces.
- **CephFS:** Attach a CephFS filesystem from an internal PVC, an external Ceph cluster, or a system-managed storage class.
-## Next steps
+## See also
-- [Quickstart](/how-to-guides/storage/): Create your first PVC in under a minute
-- [Concepts](/explanation/storage): Storage types, namespaces, and access modes explained
-- [How-to guides](/how-to-guides/storage): Step-by-step guides for PVCs, NFS, and CephFS
+- [Storage concepts](/explanation/storage)
+- [Storage how-to](/how-to-guides/storage/)
diff --git a/docs/reference/teams/index.md b/docs/reference/teams/index.md
index 0477543..e7fbd12 100644
--- a/docs/reference/teams/index.md
+++ b/docs/reference/teams/index.md
@@ -7,15 +7,13 @@ description: Group users, own resources, and control access.
Teams is where you group users, own resources, and control who can do what across your Vantage organization.
-[Get started](/how-to-guides/teams/get-started) · [Concepts](/explanation/teams)
-
## What you'll find inside
- **Team membership:** Add and remove members. Each member has a role that determines their permissions.
- **Resource ownership:** Every resource belongs to a team. Resources are visible only to team members unless explicitly shared.
- **Roles:** Admin, Engineer, Viewer, or custom permission sets. Roles control what actions members can take, from viewing cluster status to managing billing.
-## Next steps
+## See also
-- [Quickstart](/how-to-guides/teams/get-started): Create a team and add members in under two minutes
-- [Concepts](/explanation/teams): Teams, roles, and resource ownership explained
+- [Teams concepts](/explanation/teams)
+- [Manage teams how-to](/how-to-guides/teams/manage)
diff --git a/docs/reference/workbench/index.mdx b/docs/reference/workbench/index.mdx
index dbfac37..0c69a1f 100644
--- a/docs/reference/workbench/index.mdx
+++ b/docs/reference/workbench/index.mdx
@@ -1,39 +1,29 @@
---
title: Workbench
-description: AI/ML workspace, sessions, services, models, endpoints, training, pipelines, sweeps.
+description: Reference for Workbench sessions, services, training, pipelines, sweeps, models, and endpoints.
---
-# The Vantage AI Workbench
+# Workbench
Workbench is where you build, train, and serve machine-learning models on Vantage. It organizes everything into five sections, Workspace, Develop, Compute, Train, and Serve, all sharing the same compute, storage, and cost envelope.
-:::info
-**Workbench replaces the Kubeflow dashboard.** Everything you'd reach through Kubeflow Notebooks, KServe, Trainer, Katib, and the Pipelines UI is here under native Vantage primitives, without the namespaces, CRDs, and Istio routes leaking through.
-:::
-
-## Workspace
-
-- **[Observability](/reference/workbench/observability):** Cluster-wide rollups of utilization, spend, idle GPU hours, and live alerts.
-
-## Develop
+## What you'll find inside
- **[Sessions](/reference/workbench/sessions):** Interactive notebook environments, Jupyter, VS Code, RStudio, pinned to GPU pools and your team's storage.
- **[Presets](/reference/workbench/presets):** Reusable templates that define which IDE, images, compute sizes, and storage a session gets.
- **[Cloud Shell](/reference/workbench/cloud-shell):** Browser-based terminal sessions with optional Slurm access.
- **[Remote Desktop](/reference/workbench/remote-desktop):** VNC-based remote desktop sessions for full GUI access to GPU nodes.
- **[PVC Viewer](/reference/workbench/pvc-viewer):** Browser-based file browser for PersistentVolumeClaims.
-
-## Compute
-
-- **[Pools](/reference/workbench/compute-profiles):** The reusable shape of your compute: GPU type, count, autoscaling bounds, instance class.
-
-## Train
-
+- **[Compute Profiles](/reference/workbench/compute-profiles):** The reusable shape of your compute: GPU type, count, autoscaling bounds, instance class.
- **[Training Jobs](/reference/workbench/training-jobs):** Distributed training on PyTorch, DeepSpeed, or MLX runtimes. Retry, suspend, resume.
- **[Pipelines](/reference/workbench/pipelines):** Multi-step DAGs that orchestrate ingestion, training, evaluation, and deployment.
- **[Sweeps](/reference/workbench/sweeps):** Hyperparameter search with Bayesian, grid, or random algorithms, tracked end-to-end.
+- **[Models](/reference/workbench/models):** Versioned model catalog. Pull from HuggingFace or your own training runs, then deploy to an endpoint.
+- **[Endpoints](/reference/workbench/endpoints):** Inference services with autoscaling, canary rollouts, and authenticated URLs.
+- **[Observability](/reference/workbench/observability):** Cluster-wide rollups of utilization, spend, idle GPU hours, and live alerts.
+- **[Keyboard shortcuts](/reference/workbench/shortcuts):** Quick reference for Workbench keyboard shortcuts.
-## Serve
+## See also
-- **[Models](/reference/workbench/models):** Versioned model catalog. Pull from HuggingFace or your own training runs, then deploy to an endpoint.
-- **[Endpoints](/reference/workbench/endpoints):** Inference services with autoscaling, canary rollouts, and authenticated URLs.
\ No newline at end of file
+- [Workbench concepts](/explanation/workbench)
+- [Workbench how-to](/how-to-guides/workbench/get-started)
\ No newline at end of file
diff --git a/docs/tutorial.mdx b/docs/tutorial.mdx
index 23145d3..155b3d4 100644
--- a/docs/tutorial.mdx
+++ b/docs/tutorial.mdx
@@ -73,7 +73,7 @@ uvx v8x cluster create slurm-multipass-demo \
A cluster is the compute environment where your workloads run. In Vantage, it connects your infrastructure, scheduler, and worker nodes so you can submit jobs, manage capacity, and monitor execution from a single place.
-For other connection methods (Ansible, Terraform, Juju, Manual), see the [on-premises clusters guide](/reference/clusters/on-premises).
+For other connection methods (Ansible, Terraform, Juju, Manual), see the [on-premises clusters guide](/how-to-guides/clusters/on-premises).