Document registry upgrade and drift flow

docs/toolhive/guides-ui/customize-tools.mdx

@@ -57,6 +57,53 @@ you to start the server first.
 
 :::
 
+## Drift and registry mismatches
+
+ToolHive compares the running MCP server against its registry definition and
+surfaces alerts on the customize tools page when there's a mismatch. Two kinds
+of drift are reported.
+
+### Tag drift detected
+
+If the local image tag differs from the tag in the registry, the page shows a
+**Tag drift detected** alert. The alert reads:
+
+> This image has drifted from the version in the registry.
+
+It then lists the **Local** and **Registry** tags so you can see what's out of
+date, followed by:
+
+> Please upgrade to the latest one. Enabled tools are up to date, but some
+> disabled tools may no longer match the current image.
+
+You can still toggle enabled tools while this alert is showing, but the tool
+list reflects the running image rather than the registry definition. Disabled
+tools may correspond to tools that no longer exist in the new image.
+
+:::note
+
+Resolving tag drift requires upgrading the server image. See
+[Upgrade registry image versions](./run-mcp-servers.mdx#upgrade-registry-image-versions)
+for the steps, including the dialog you'll see when environment variables differ
+between versions.
+
+:::
+
+### Tools differ from registry
+
+If the running server's tool list doesn't match the registry definition for the
+current image, the page shows a **Tools differ from registry** alert. The alert
+reads:
+
+> The tools available in the running server don't fully match the registry
+> definition.
+
+Tools that exist in the registry definition but are absent from the running
+server are listed under **Missing from server:** as badges, one per tool. This
+typically means the upstream MCP server changed its tool surface without a
+matching registry update, or that the running container doesn't match the image
+referenced by the registry entry.
+
 ## Enable or disable tools
 
 On the customize tools page:

docs/toolhive/guides-ui/run-mcp-servers.mdx

@@ -582,6 +582,62 @@ When you quit the application, ToolHive prompts you to stop all running MCP
 servers. The running servers are recorded and ToolHive restarts them
 automatically the next time you launch the application.
 
+### Upgrade registry image versions
+
+For MCP servers installed locally from the registry, ToolHive shows an upgrade
+option on the server card when a newer image tag is available in the registry.
+The option appears only when all of the following are true:
+
+- The server runs locally, not as a remote MCP server.
+- The server was installed from a registry that includes an `image` field.
+- The local image tag differs from the registry image tag.
+
+When an upgrade is available, the server card shows an upgrade icon control next
+to the **start** and **stop** actions. The same action is available in the
+server's overflow (`⋮`) menu as **Update to `<TAG>`**, where `<TAG>` is the
+registry image tag.
+
+The control's tooltip reads:
+
+> Update available: `<LOCAL_TAG>` → `<REGISTRY_TAG>`
+
+ToolHive disables the menu item while the server is being removed or updated.
+
+Selecting the upgrade control opens the **Update to latest version** dialog.
+ToolHive compares the local server's environment variables against the registry
+definition for the new tag and shows one of two outcomes:
+
+- **No configuration drift:** ToolHive shows the message:
+
+  > No configuration changes detected between versions.
+
+  The dialog offers **Update** and **Cancel**. Click **Update** to pull the new
+  image and restart the server with your existing configuration, or **Cancel**
+  to dismiss the dialog.
+
+- **Configuration drift:** ToolHive lists changes under **New variables in this
+  version:** (with `secret`, `env`, and `required` badges where applicable) and
+  **Variables no longer in registry:**. The dialog offers **Edit and review**
+  and **Cancel** instead of **Update**, because new values may be required.
+  - Click **Edit and review** to open the edit flow with the new image tag and
+    any added variables prefilled.
+  - Supply values, adjust secrets, and remove obsolete variables, then save.
+  - Click **Cancel** to keep the current version.
+
+The **Edit and review** flow only updates the server when you save the edit
+form. If you cancel out of the edit flow, the server keeps its current image tag
+and configuration.
+
+:::tip
+
+Upgrading the image tag does not reconcile drift in the server's tool list. If
+the new image adds, removes, or renames tools, review the changes on the
+**Customize tools** page. See
+[Drift and registry mismatches](./customize-tools.mdx#drift-and-registry-mismatches)
+for details.
+
+:::
+
 ## Next steps
 
 - Connect ToolHive to AI clients like GitHub Copilot or Cursor using the