vantagecompute · wardbryan3 · Aug 13, 2026
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -5,11 +5,6 @@ description: Notable changes to Vantage.
 
 # Changelog
 
-Changelog entries are published with each product release. Check back here for updates on new features, improvements, and bug fixes.
-
-Notable recent changes:
+For detailed release notes, see our [GitHub releases](https://github.com/vantagecompute/vantage-docs/releases).
 
-- **Storage section added:** PVCs, NFS, and CephFS how-to guides for Kubernetes clusters.
-- **Clusters section restructured:** New get-started, concepts, and provider-specific how-to guides.
-
-For detailed release notes, see the [GitHub releases page](https://github.com/vantagecompute/v8x/releases).
+Changelog entries are published with each product release. Check back here for updates on new features, improvements, and bug fixes.
diff --git a/docs/explanation/clusters.mdx b/docs/explanation/clusters.mdx
@@ -1,5 +1,5 @@
 ---
-title: Concepts
+title: Clusters
 description: Mental models that show up across every cluster type.
 sidebar_position: 2
 ---

diff --git a/docs/explanation/compute-providers.mdx b/docs/explanation/compute-providers.mdx
@@ -1,5 +1,5 @@
 ---
-title: Concepts
+title: Compute providers
 description: Three mental models behind every cloud account in Vantage.
 sidebar_position: 2
 ---
@@ -16,7 +16,7 @@ One cloud account can back multiple clusters.
 
 ## Providers
 
-Vantage supports six provider types:
+Vantage supports **five** provider types:
 
 | Provider | What it's for |
 |---|---|

diff --git a/docs/explanation/concepts/jobs-and-pipelines.md b/docs/explanation/concepts/jobs-and-pipelines.md
@@ -1,11 +1,11 @@
 ---
 title: Jobs and pipelines
-description: Finite computational work and the DAGs that orchestrate it.
+description: Finite computational work and the directed acyclic graphs (DAGs) that orchestrate it.
 ---
 
 # Jobs and pipelines
 
-Jobs are finite computational workloads, single-shot or distributed. Pipelines are multi-step DAGs that string jobs (and other steps) together for ingestion, training, evaluation, and deployment.
+Jobs are finite computational workloads, single-shot or distributed. Pipelines are multi-step directed acyclic graphs (DAGs) that string jobs (and other steps) together for ingestion, training, evaluation, and deployment.
 
 ## Scripts and submissions
 
@@ -17,7 +17,7 @@ Vantage stores scripts in a script library with version history. You can create
 
 Templates are Jinja2-based blueprints with parameterized variables. Write a template once with placeholders for dataset paths, cluster config, or resource requirements. When you render it, Vantage fills in the values and produces a concrete script.
 
-Use templates when your team needs standardized job definitions, you control the structure, they fill in the parameters.
+Use templates when your team needs standardized job definitions. You control the structure, and they fill in the parameters.
 
 ## Pipelines
 
@@ -28,4 +28,4 @@ Unlike a single job that runs a self-contained workload, a pipeline coordinates
 ## Cross-references
 
 - [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.
+- Jobs, scripts, templates, and submissions have their own full section under [Reference: Jobs](/reference/jobs). Pipelines are covered under [Reference: 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
@@ -5,6 +5,10 @@ description: How permissions, ownership, and collaboration work.
 
 # Teams and IAM
 
+:::note
+This page provides a combined overview. For deeper coverage, see [Teams](/explanation/teams) and [IAM](/explanation/iam).
+:::
+
 Teams group users and own resources. IAM (identity and access management) controls what each team member can do, read, write, delete, deploy. Every resource in Vantage belongs to a team, and every action is authorized against that team's permissions.
 
 ## Teams
@@ -19,7 +23,11 @@ Vantage uses role-based access control (RBAC). A role is a set of permissions, c
 
 ## 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.
+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.
+
+## Roles vs. permission groups
+
+Roles and permission groups are independent systems that control access at different levels. Roles are team-level tool permissions (for example, Admin, Engineer, Viewer within a team). Permission groups are platform-wide IAM scopes (for example, Full Admin, Cluster Admin). A user's effective access is the combination of both: their permission group determines what actions are available across the platform, and their team role determines what they can do within a specific team.
 
 ## Cross-references
 

diff --git a/docs/explanation/concepts/why-teams-and-iam.md b/docs/explanation/concepts/why-teams-and-iam.md
@@ -62,7 +62,7 @@ The ML Research team owns a workspace with four A100 GPUs. The Platform Engineer
 
 - **Alice** can see the A100 workspace (team membership) and can do anything in it (Full Admin permissions), create sessions, manage storage, invite members, adjust quota.
 - **Bob** can see the same A100 workspace (same team) but can only run workloads and manage his own resources (Regular User permissions). He cannot invite new members or adjust quota.
-- **Carol** cannot see the A100 workspace at all, she is not on the ML Research team. She can manage clusters across the organization (Cluster Admin permissions), but only within the workspaces her team owns.
+- **Carol** cannot see the A100 workspace at all because she is not on the ML Research team. She can manage clusters across the organization (Cluster Admin permissions), but only within the workspaces her team owns.
 
 If Alice shares a storage volume with Platform Engineering, Carol can see that volume. But her actions on it are still governed by her IAM permissions and any access level Alice set when sharing.
 

diff --git a/docs/explanation/concepts/workbench-ml-stack.md b/docs/explanation/concepts/workbench-ml-stack.md
@@ -53,7 +53,7 @@ Development is interactive, exploratory work, writing code, loading data, testin
 
 Sessions start from a **preset:** a reusable template that bundles the IDE type, base container image, compute sizes, and default storage volumes. Presets standardize what "a development environment" looks like across a team, so every engineer gets the same image, the same libraries, and the same GPU options without configuring them from scratch.
 
-For lighter-weight access, **Cloud Shell** provides a browser terminal and **Remote Desktop** provides VNC-based GUI access. Both are cheaper and faster to spin up than a full session.
+For lighter-weight access, **Cloud Shell** provides a browser terminal and **Remote Desktop** provides noVNC-based GUI access. Both are cheaper and faster to spin up than a full session.
 
 The develop phase is where most time is spent and where iteration speed matters most. Sessions give you a full environment with the same compute you will eventually train on, so there is no "it worked on my laptop" gap between development and training.
 
@@ -73,7 +73,7 @@ The relationship between these components: a pipeline may orchestrate several tr
 
 Serving bridges the gap between a trained model and a production API.
 
-The **model registry** is a versioned catalog of model artifacts. Sources include HuggingFace, training job outputs, or direct uploads. Each model can have multiple versions. The registry is the handoff point, it decouples "who produced this model" from "who is deploying it."
+The **model registry** is a versioned catalog of model artifacts. Sources include HuggingFace, training job outputs, or direct uploads. Each model can have multiple versions. The registry is the handoff point. It decouples "who produced this model" from "who is deploying it."
 
 **Endpoints** serve a registered model behind an authenticated, autoscaling HTTP URL. Workbench distinguishes two endpoint kinds because their tuning surfaces are different:
 

diff --git a/docs/explanation/concepts/workspaces.md b/docs/explanation/concepts/workspaces.md
@@ -5,13 +5,13 @@ description: Your team's slice of the cluster, with quota, RBAC, and a cost enve
 
 # Workspaces
 
-A workspace is your team's slice of the Vantage cluster. Workspaces hold quota (CPUs, memory, GPUs, storage), an RBAC scope, and a cost envelope. Resources you create in Vantage live inside one workspace at a time. The current workspace is shown in the top-right of the screen, switch with the workspace picker.
+A workspace is your team's slice of the Vantage cluster. Workspaces hold quota (CPUs, memory, GPUs, storage), an RBAC scope, and a cost envelope. Resources you create in Vantage live inside one workspace at a time. The current workspace is shown in the top-right of the screen. Switch with the workspace picker.
 
 ## Quota
 
 Every workspace has a resource ceiling: CPU cores, memory, GPU count, and storage capacity. Quota is set by your admin and enforced at resource creation time. When you try to start a Workbench session or submit a job that would exceed the workspace quota, Vantage blocks it.
 
-Quota is not the same as usage. A workspace might have 16 GPUs of quota but only 4 in active use, the remaining 12 are available for new workloads. Check your workspace's current utilization on the Dashboard.
+Quota is not the same as usage. A workspace might have 16 GPUs of quota but only 4 in active use. The remaining 12 are available for new workloads. Check your workspace's current utilization on the Dashboard.
 
 ## Cost envelope
 

diff --git a/docs/explanation/federations.mdx b/docs/explanation/federations.mdx
@@ -8,7 +8,7 @@ sidebar_position: 2
 
 Federations answer a simple question: *what if you could submit a job without deciding which cluster should run it?*
 
-A federation groups multiple Vantage clusters into a single logical compute pool. Instead of choosing a cluster at submission time, you choose the federation, and Vantage routes the job to a member cluster that has the capacity to run it. The individual clusters keep their own schedulers, partitions, compute pools, and configuration, the federation is a layer above them, not a replacement for them.
+A federation groups multiple Vantage clusters into a single logical compute pool. Instead of choosing a cluster at submission time, you choose the federation, and Vantage routes the job to a member cluster that has the capacity to run it. The individual clusters keep their own schedulers, partitions, compute pools, and configuration. The federation is a layer above them, not a replacement for them.
 
 ## Why federations exist
 
@@ -66,7 +66,7 @@ Federations are not limited to a single scheduler or provider. A single federati
 - **On-premises clusters** alongside cloud clusters
 - **Clusters provisioned through different methods** (CloudFormation, Terraform, Ansible, Juju, manual connector)
 
-This flexibility is what makes federations useful for hybrid and multi-cloud strategies. The federation does not need its member clusters to be identical, it only needs them to be registered in Vantage and in a `Ready` state.
+This flexibility is what makes federations useful for hybrid and multi-cloud strategies. The federation does not need its member clusters to be identical. It only needs them to be registered in Vantage and in a `Ready` state.
 
 However, keep in mind that a Slurm job script is not interchangeable with a Kubernetes workload definition. If a federation contains both Slurm and Kubernetes clusters, routing will only consider clusters whose scheduler type matches the submitted job type.
 

diff --git a/docs/explanation/iam.mdx b/docs/explanation/iam.mdx
@@ -1,5 +1,5 @@
 ---
-title: Concepts
+title: IAM
 description: Four mental models behind IAM in Vantage.
 ---
 

diff --git a/docs/explanation/jobs.mdx b/docs/explanation/jobs.mdx
@@ -1,5 +1,5 @@
 ---
-title: Concepts
+title: Jobs
 description: Key mental models for the Jobs section, including scripts, templates, submissions, and the relationships between them.
 ---
 

diff --git a/docs/explanation/licenses.mdx b/docs/explanation/licenses.mdx
@@ -1,5 +1,5 @@
 ---
-title: Concepts
+title: Licenses
 description: Four mental models behind license management in Vantage.
 ---
 

diff --git a/docs/explanation/storage.mdx b/docs/explanation/storage.mdx
@@ -1,5 +1,5 @@
 ---
-title: Concepts
+title: Storage
 description: Storage types, namespaces, access modes, and storage classes in Vantage.
 sidebar_position: 2
 ---
@@ -14,7 +14,7 @@ Vantage exposes three storage primitives on Kubernetes clusters.
 
 | Type | What it is | Best for |
 |---|---|---|
-| **PVC** | A Persistent Volume Claim backed by a storage class on the cluster | Single-namespace workloads that need durable block or file storage |
+| **PVC (Persistent Volume Claim)** | A storage request backed by a storage class on the cluster | Single-namespace workloads that need durable block or file storage |
 | **NFS** | A network file share, either an external NFS server or a PVC exposed over NFS | Sharing data across namespaces or mounting the same volume in multiple pods simultaneously |
 | **CephFS** | A CephFS filesystem, from an internal PVC, an external Ceph cluster, or a system storage class | High-throughput parallel access across many nodes |
 

diff --git a/docs/explanation/teams.mdx b/docs/explanation/teams.mdx
@@ -1,5 +1,5 @@
 ---
-title: Concepts
+title: Teams
 description: Four mental models behind Teams and IAM.
 ---
 

diff --git a/docs/explanation/workbench.mdx b/docs/explanation/workbench.mdx
@@ -17,7 +17,7 @@ A reusable template (WorkspaceKind) that defines what a session looks like befor
 
 ## Service
 
-A lightweight, browser-accessible tool that runs on cluster compute. Services include [Cloud Shell](/reference/workbench/cloud-shell) (terminal access), [Remote Desktop](/reference/workbench/remote-desktop) (VNC GUI), and [PVC Viewer](/reference/workbench/pvc-viewer) (file browser). They share a common lifecycle: create, open, and delete. They are also cheaper and faster to spin up than a full session.
+A lightweight, browser-accessible tool that runs on cluster compute. Services include [Cloud Shell](/reference/workbench/cloud-shell) (terminal access), [Remote Desktop](/reference/workbench/remote-desktop) (noVNC GUI), and [PVC Viewer](/reference/workbench/pvc-viewer) (file browser). They share a common lifecycle: create, open, and delete. They are also cheaper and faster to spin up than a full session.
 
 ## Compute pool
 
@@ -41,4 +41,10 @@ Every active resource accumulates spend. Workbench shows three numbers: **$/hr**
 
 ## Observability
 
-Detail pages link out to Grafana dashboards scoped to that resource. Cluster-wide metrics live on the [Observability tab](/reference/workbench/observability).
+Detail pages link out to Grafana dashboards scoped to that resource. Cluster-wide metrics live on the [Observability tab](/reference/workbench/observability).
+
+## See also
+
+- [Pipeline anatomy](/explanation/workbench/pipeline-anatomy)
+- [Sweep algorithms](/explanation/workbench/sweep-algorithms)
+- [Predictive vs. LLM endpoints](/explanation/workbench/predictive-vs-llm)
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -11,7 +11,7 @@ description: Terms used across the Vantage docs.
 
 **API key:** A token used for programmatic access to the Vantage API. Generated from your profile settings.
 
-**Authentication:** How you prove identity to Vantage. Options: OAuth (sign in with Google or GitHub) or federated SSO (your own identity provider via OIDC).
+**Authentication:** How you prove identity to Vantage. Options: OAuth (sign in with Google or GitHub) or federated SSO (your own identity provider via OpenID Connect, or OIDC).
 
 **Canary:** A new endpoint version receiving a fraction of traffic during a rollout. Gradually shifts traffic as confidence increases.
 
@@ -23,6 +23,8 @@ description: Terms used across the Vantage docs.
 
 **Cluster:** A physical Kubernetes or Slurm cluster Vantage manages. Workspaces live inside clusters; users can switch between clusters their team has access to.
 
+**Compute pool:** A pool of identically-sized machines on a Kubernetes cluster (formerly called a node group), scaled up and down automatically. Each compute pool is a billing unit.
+
 **Compute profile:** Reusable shape of compute (GPU + count + instance type + bounds).
 
 **Compute provider:** A supported source of compute: AWS, Azure, GCP, LXD, or On-Premises. Each has different credential requirements and capabilities.
@@ -55,8 +57,6 @@ description: Terms used across the Vantage docs.
 
 **Node:** A single machine in a cluster that runs workloads. Cloud nodes are provisioned and deprovisioned automatically by Vantage.
 
-**Compute pool:** A pool of identically-sized machines on a Kubernetes cluster (formerly called a node group), scaled up and down automatically. Each compute pool is a billing unit.
-
 **Organization:** The top-level account containing all your users, teams, clusters, and resources. Billing and global settings are managed at the organization level.
 
 **Partition:** A job queue on a Slurm cluster. Each partition targets a pool of nodes and applies rules: max run time, allowed users, priority class.
@@ -65,16 +65,19 @@ description: Terms used across the Vantage docs.
 
 **Persistent Volume Claim (PVC):** A Kubernetes storage request backed by a storage class. Namespace-scoped and tied to a specific performance tier.
 
-**Pipeline:** A multi-step DAG of containerized tasks.
+**Pipeline:** A multi-step directed acyclic graph (DAG) of containerized tasks.
 
 **Preset:** A pre-configured session environment that pins image, compute profile, and storage settings. Useful for standardizing team development environments.
 
 **Runtime:** A pre-built training environment that combines a framework, image, and parallelism strategy.
 
-**Service:** An add-on capability within Workbench: Cloud Shell (browser terminal), Remote Desktop (X2Go GUI), or PVC Viewer (file browser).
+<!-- TODO(vantage): confirm Remote Desktop protocol -- most pages say noVNC/VNC, but reference/workbench/sessions/remote-desktops.md says X2Go -->
+**Service:** An add-on capability within Workbench: Cloud Shell (browser terminal), Remote Desktop (noVNC GUI), or PVC Viewer (file browser).
 
 **Session:** An interactive notebook or development environment (JupyterLab, VS Code, RStudio) running on managed compute.
 
+**Slurm:** An open-source job scheduler for HPC clusters, used by Vantage for batch workload scheduling and resource management.
+
 **Storage class:** A Kubernetes storage profile that defines the provisioner, performance tier, and reclaim policy for PVCs.
 
 **Sweep:** A hyperparameter-search experiment containing many trial runs.
@@ -89,4 +92,6 @@ description: Terms used across the Vantage docs.
 
 **Vantage-hosted:** A license server Vantage manages for you. Automatic updates, monitoring, and high availability.
 
-**Workspace:** Your team's slice of the Vantage cluster, with quota, RBAC, and a cost envelope.
+**Workbench:** The Vantage module for interactive development sessions, training jobs, inference endpoints, and ML pipelines.
+
+**Workspace:** Your team's slice of the Vantage cluster, with quota, role-based access control (RBAC), and a cost envelope.
diff --git a/docs/how-to-guides/catalog/deploy-nim-model.mdx b/docs/how-to-guides/catalog/deploy-nim-model.mdx
@@ -5,7 +5,7 @@ description: Walk through the four-step deploy wizard to launch an NVIDIA NIM in
 
 # Deploy a NIM model from the Catalog
 
-Use the NIM deploy wizard when you want to serve one of the 277 curated NVIDIA NIM models as an inference endpoint. The wizard handles version selection, GPU compatibility, platform choice, scaling, and ingress in four steps.
+Use the NIM deploy wizard when you want to serve one of the hundreds of curated NVIDIA NIM models as an inference endpoint. The wizard handles version selection, GPU compatibility, platform choice, scaling, and ingress in four steps.
 
 <div className="guide-intro">
 	<p>

diff --git a/docs/how-to-guides/catalog/get-started.mdx b/docs/how-to-guides/catalog/get-started.mdx
@@ -36,7 +36,7 @@ Click **Catalog** in the left sidebar to open the Catalog. Five tabs organize th
 
 | Source | What it contains |
 |---|---|
-| **NVIDIA NIM** | 277 curated inference microservices. Each model ships as an optimized container with a built-in deploy wizard. |
+| **NVIDIA NIM** | Hundreds of curated inference microservices. Each model ships as an optimized container with a built-in deploy wizard. |
 | **Hugging Face** | Models synced from Hugging Face Hub metadata. Browse the synced catalog or add a specific model by its Hub Model ID. |
 | **Local** | Your organization's own registered models. Models registered here can be deployed the same way as NIM or Hugging Face models. |
 | **NGC Containers** | Framework images for training, workspace, and serving workloads (e.g. NeMo Framework, PyTorch, Triton Inference Server, CUDA, JAX). |