diff --git a/docs/changelog.d/hephd-self-update.feature.md b/docs/changelog.d/hephd-self-update.feature.md
new file mode 100644
index 0000000..90cd33d
--- /dev/null
+++ b/docs/changelog.d/hephd-self-update.feature.md
@@ -0,0 +1 @@
+Opt-in (default off) **hephd self-update**: `hephd --self-update` polls the forge for a newer release on an interval and, when one appears, rebuilds via `cargo install` from the release tag (anonymous HTTPS clone of the public repo — no credentials) and restarts onto the new binary. Enable it on the managed service with `heph daemon start --self-update` (which also bakes a cargo-capable `PATH` into the launchd/systemd unit and switches systemd to `Restart=always` so a clean self-exit respawns). The install mechanism is verified end-to-end; a live cross-version upgrade is confirmed on the first release after this lands. Also hardens hub resilience: the daemon's HTTP client now has a 30s timeout so a black-hole hub can't stall the sync/self-update loop.
diff --git a/docs/how-to/self-update/hephd-self-update.md b/docs/how-to/self-update/hephd-self-update.md
index e9b679a..dbd0e8a 100644
--- a/docs/how-to/self-update/hephd-self-update.md
+++ b/docs/how-to/self-update/hephd-self-update.md
@@ -3,8 +3,6 @@ title: hephd self-update
 modified: 2026-06-04
 tags:
   - how-to
-status: active
-branch: mikado/hephd-self-update
 requires:
   - self-restart-after-update
   - verify-hub-dropout-resilience
@@ -12,10 +10,16 @@ requires:
 
 # hephd self-update
 
-**Goal (desired end state).** An opt-in, **default-off** mode where `hephd`
-periodically polls the forge for a newer release and, when one exists,
-rebuilds via `cargo install` from the release tag and restarts itself onto the
-new binary — unattended.
+**Implemented.** An opt-in, **default-off** mode where `hephd` periodically
+polls the forge for a newer release and, when one exists, rebuilds via `cargo
+install` from the release tag and restarts itself onto the new binary —
+unattended. Enable on the managed service with `heph daemon start --self-update`
+(see [[run-the-daemon]]).
+
+> **One remaining live check (owner):** the install mechanism is verified
+> end-to-end (anonymous public HTTPS `cargo install`), and the detection/apply
+> logic is unit-tested, but a real older→newer upgrade can only be observed when
+> the next release lands. Enable `--self-update` and confirm the upgrade then.
 
 ## End state