av · ahundt · May 21, 2025
diff --git a/docs/1.-Harbor-User-Guide.md b/docs/1.-Harbor-User-Guide.md
@@ -272,6 +272,93 @@ harbor config ls | grep CACHE
 open $(eval echo "$(harbor config get hf.cache)")
 ```
 
+### Update, Revert, and Manage Container, Service, Frontend, Backend, and Tool Versions
+
+This section explains how to safely update, try new versions (including git tags or `latest`), and revert any Harbor-managed container, service, frontend, backend, or tool. These workflows let you experiment and quickly recover to Harbor’s tested defaults.
+
+### Updating a Container, Service, Frontend, Backend, or Tool
+
+To bring a container or service (such as `webui`, `ollama`, etc.) up to the latest available version:
+
+```bash
+harbor pull <service>
+harbor up <service>
+```
+
+This downloads and restarts the latest image for the selected component.
+
+### Trying a Specific Version or Tag
+
+You can run a specific version of a container/service by either:
+
+- Editing your `.env` file and setting the version:
+  ```
+  WEBUI_VERSION=0.6.9
+  ```
+- Or, if the service supports it, using the Harbor CLI alias:
+  ```bash
+  harbor webui version 0.6.9
+  harbor webui version latest
+  harbor webui version main
+  ```
+- Or, you can set the version directly via config for any service:
+  ```bash
+  harbor config set <service>.version <tag>
+  # Example:
+  harbor config set openhands.version main
+  ```
+> [!NOTE]
+> Harbor’s default version for a service is whatever is set in its configuration at release—this may be `latest`, `main`, or a specific tag. If you require maximum stability, pin your service to a known-good version.
+
+You can use explicit git version tags like `v1.2.3`, `latest`, or `main`.
+**Note:** `latest` and `main` may not always be tested or stable.
+
+### Reverting to the Safe Tested Default
+
+To revert back to the version Harbor supplies as its “safe tested default” for any service/container:
+
+1. Remove the version override from your `.env` file (delete the line or comment it out).
+2. Pull and restart the service:
+   ```bash
+   harbor pull <service>
+   harbor up <service>
+   ```
+
+This will launch the default version Harbor is configured to use for your stack.
+
+### Updating Harbor CLI/Core
+
+To update Harbor CLI itself:
+
+```bash
+harbor update
+```
+
+To try a specific Harbor CLI version or the latest development build:
+
+```bash
+harbor update v1.2.3
+harbor update --latest
+```
+
+**Note:** `--latest` may be a development build and not always tested.
+
+### Version Troubleshooting and Recovery
+
+If updating or trying a new version causes issues, use the revert workflow above to quickly return to a working state. The default version is always what Harbor provides for your release.
+
+### Version Summary Reference
+
+| Task                        | Command or Action                                                           |
+|-----------------------------|-----------------------------------------------------------------------------|
+| Update Harbor               | `harbor update` or `harbor update vX.Y.Z`/`harbor update --latest`          |
+| Update service/container    | `harbor pull <service> && harbor up <service>`                              |
+| Pin to version/tag          | Edit `.env` (e.g., `WEBUI_VERSION=...`) or `harbor <service> version <tag>` |
+| Try latest                  | Use `latest` as version in `.env` or CLI alias                              |
+| Revert to default           | Remove version from `.env`, then `harbor pull <service>` and `harbor up <service>`              |
+
+**See also:** [Configuring Services](#configuring-services), [Harbor CLI Reference](./3.-Harbor-CLI-Reference.md)
+
 ## Harbor Profiles
 
 When you have multiple configurations for different use-cases, you can save them as profiles for easy switching. Profiles include everything that can be configured via `harbor config` (most of the settings configured via CLI) and are stored in the Harbor workspace. They are just a way to swap between `.env` files using command line.
@@ -354,6 +441,9 @@ Please refer to the [Satellites](2.-Services#satellite-services) section in the
 
 Harbor combines many services and configurations together, all of which are in the constant motion, receiving updates and changes. This can sometimes lead to issues. Harbor comes with a set of tools to help you diagnose and fix these issues.
 
+> [!TIP]
+> To change versions of Harbor, its components, and restore safe tested defaults see [Update, Revert, and Manage Container, Service, Frontend, Backend, and Tool Versions](1.-Harbor-User-Guide.md#update-revert-and-manage-container-service-frontend-backend-and-tool-versions).
+
 ### Service State
 
 When something unexpected happens, the very first thing to check is the state of the service.

diff --git a/docs/1.0.-Installing-Harbor.md b/docs/1.0.-Installing-Harbor.md
@@ -120,6 +120,9 @@ harbor open
 - [Harbor CLI Reference](./3.-Harbor-CLI-Reference)
 - [Harbor Services](./2.-Services)
 
+> [!TIP]
+> To change versions of Harbor, its components, and restore safe tested defaults see [Update, Revert, and Manage Container, Service, Frontend, Backend, and Tool Versions](1.-Harbor-User-Guide.md#update-revert-and-manage-container-service-frontend-backend-and-tool-versions).
+
 ### Harbor App
 
 > [!NOTE]

diff --git a/docs/3.-Harbor-CLI-Reference.md b/docs/3.-Harbor-CLI-Reference.md
@@ -85,7 +85,7 @@ harbor tunnels add webui
 
 #### Capabilities detection
 
-By default, Harbor will try to infer some capabilities of the host (and match related [cross files](./6.-Harbor-Compose-Setup#cross-service-file)), such as Nvidia GPU availability (`nvidia` capability) or presence of modern Docker Compose features (`mdc` capability).
+By default, Harbor will try to infer some capabilities of the host (and match related [cross files](./6.-Harbor-Compose-Setup.md#cross-service-files)), such as Nvidia GPU availability (`nvidia` capability) or presence of modern Docker Compose features (`mdc` capability).
 
 If this behavior is undesirable or you want to provide a manual list of capabilities, you can disable the automatic detection.
 
@@ -1295,6 +1295,9 @@ This process won't overwrite user-defined variables, only add new ones.
 harbor config update
 ```
 
+> [!TIP]
+> To change versions of Harbor, its components, and restore safe tested defaults see [Update, Revert, and Manage Container, Service, Frontend, Backend, and Tool Versions](1.-Harbor-User-Guide.md#update-revert-and-manage-container-service-frontend-backend-and-tool-versions).
+
 ### `harbor profile`
 
 > Alias: `harbor profiles`, `harbor p`