diff --git a/hive-c0re/src/matrix.rs b/hive-c0re/src/matrix.rs
index 5621e2ba..f44e62e0 100644
--- a/hive-c0re/src/matrix.rs
+++ b/hive-c0re/src/matrix.rs
@@ -47,6 +47,7 @@ pub const HIVE_ADMIN_LOCALPART: &str = "hive";
 
 /// Host path for the hive admin matrix access token. Outside every
 /// purgeable path — not deleted by `destroy --purge` on any agent.
+#[must_use]
 pub fn admin_token_path() -> PathBuf {
     PathBuf::from("/var/lib/hyperhive/matrix-admin-token")
 }
@@ -321,7 +322,7 @@ pub async fn ensure_user_for(
                     tracing::info!(%name, "matrix: migrated password file to non-purgeable location");
                 }
             } else {
-                tracing::warn!(%name, error = ?e, "matrix: password migration failed (old path stays)");
+                tracing::warn!(%name, rename_error = ?e, "matrix: password migration failed — could not read old path (old path stays)");
             }
         } else {
             tracing::info!(%name, "matrix: migrated password file to non-purgeable location");
@@ -355,15 +356,9 @@ pub async fn ensure_user_for(
                 .with_context(|| {
                     format!(
                         "matrix: user {name} already exists in homeserver but the stored \
-                         password is missing — manual recovery:\n\
-                         1. reset the password via the matrix admin API:\n\
-                            curl -X PUT http://localhost:8008/_synapse/admin/v2/users/@{name}:<server> \\\n\
-                              -H 'Authorization: Bearer <admin-token>' \\\n\
-                              -d '{{\"password\": \"<new-pw>\"}}'\n\
-                         2. write the new password to {pw_path}:\n\
-                            echo '<new-pw>' > {pw_path} && chmod 600 {pw_path}\n\
-                         3. run: hivectl matrix create-user {name}",
-                        pw_path = pw_path.display()
+                         password is missing — run:\n\
+                         hivectl matrix reset-password {name}\n\
+                         hivectl matrix create-user {name}"
                     )
                 })?;
             login_user(client, name, &stored).await.with_context(|| {
@@ -462,7 +457,7 @@ pub async fn sync_agent_standalone(name: &str) {
 /// admin rights which this fn bootstraps); on a fresh homeserver the
 /// first-registered rule fires automatically; on an existing homeserver
 /// the operator must promote the account once via `hivectl matrix
-/// promote-user hive --server <name>` or the conduit admin room.
+/// `hivectl matrix promote-user hive` or the conduit admin room.
 pub async fn ensure_admin_user(client: &reqwest::Client, register_token: &str) -> Result<()> {
     use std::os::unix::fs::PermissionsExt;
     let path = admin_token_path();