From 8bf4e5a7abd58b536614e1b54ff1f277871fe506 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 26 Aug 2026 09:54:20 -0700
Subject: [PATCH] docs: image provenance marker and the shared refusal gate
 (#91277 Phase 3)

---
 website/docs/getting-started/updating.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/website/docs/getting-started/updating.md b/website/docs/getting-started/updating.md
index 4ee1bc4c16..5ae1f14787 100644
--- a/website/docs/getting-started/updating.md
+++ b/website/docs/getting-started/updating.md
@@ -260,6 +260,10 @@ uv pip install -e ".[all]"
 Rolling back may cause config incompatibilities if new options were added. Run `hermes config check` after rolling back and remove any unrecognized options from `config.yaml` if you encounter errors.
 :::
 
+### Image-managed installs (Docker): the provenance marker
+
+Published Docker images bake a small read-only marker (`/etc/hermes/image-provenance.json`) that authoritatively identifies the filesystem as image-managed. `hermes update`, `hermes update --check`, and the dashboard's Update button all consult it before touching anything: on an image-managed install they refuse cleanly (exit code 2), print the actual update command (`docker pull nousresearch/hermes-agent:latest`), and write a `refused` receipt so fleet tooling can see the attempt happened. The marker wins even when a source checkout is bind-mounted into the container — the refusal is based on what the running filesystem *is*, not what it looks like. A damaged marker still refuses (fail-closed). Nix- and apt-managed installs refuse through the same gate using the existing detection.
+
 ### Note for Nix users
 
 Nix is no longer an explicitly supported install path (best-effort only) — see [Nix Setup](./nix-setup.md). If you installed via Nix flake, updates are managed through the Nix package manager: