diff --git a/README.md b/README.md
index c5dc1ad..f60d370 100644
--- a/README.md
+++ b/README.md
@@ -85,14 +85,52 @@ LAN or Tailscale only — never expose to the internet.
 
 ```bash
 # Quick local run (no gunicorn needed, must have flask installed):
-MICRONAS_USER=admin MICRONAS_PASS=secret flask --app app.py run --debug --host=0.0.0.0
+MICRONAS_USER=admin MICRONAS_PASS_HASH="$(python3 -c "
+import hashlib, os
+s=os.urandom(16).hex()
+h=hashlib.pbkdf2_hmac('sha256',b'secret',s.encode(),260000).hex()
+print(f'{s}\${h}')
+")" flask --app app.py run --debug --host=0.0.0.0
 ```
 
+Or use plaintext for dev only (still supported): `MICRONAS_USER=admin MICRONAS_PASS=secret flask --app app.py run --debug`
+
 Note: SMB/NFS/user management calls require root and the relevant daemons — run on the actual LXC for full testing.
 
 ## Auth
 
-All routes require a login session. On first run you are redirected to `/setup` to create the admin account. Credentials are stored hashed in `/etc/micronas/micronas.env`. The WebDAV htpasswd file lives at `/etc/micronas/webdav.passwd` (readable by `www-data`, not world-readable).
+All routes require a login session. On first run you are redirected to `/setup` to create the admin account. Credentials are stored hashed (PBKDF2-HMAC-SHA256, 260 000 iterations) in `/etc/micronas/micronas.env`. The WebDAV htpasswd file lives at `/etc/micronas/webdav.passwd` (group-readable by `www-data`, not world-readable).
+
+**Changing the admin password** — click the ⚙ Settings button in the top-right corner. Enter your current password to confirm, then set a new username and/or password. You will be logged out automatically and redirected to login.
+
+## Upgrading from an older install (path migration)
+
+If you installed MicroNAS before the `/etc/micronas/` directory was introduced, run this once:
+
+```bash
+mkdir -p /etc/micronas
+[ -f /etc/micronas.env ] && mv /etc/micronas.env /etc/micronas/micronas.env
+[ -f /etc/micronas-webdav.passwd ] && mv /etc/micronas-webdav.passwd /etc/micronas/webdav.passwd
+chown root:www-data /etc/micronas/webdav.passwd
+chmod 640 /etc/micronas/webdav.passwd
+# Patch the Apache config if it still references the old path
+sed -i 's|/etc/micronas-webdav.passwd|/etc/micronas/webdav.passwd|' \
+    /etc/apache2/conf-available/micronas-webdav.conf
+cp /opt/micronas/micronas.service /etc/systemd/system/
+systemctl daemon-reload && systemctl restart micronas && systemctl reload apache2
+```
+
+---
+
+## User management
+
+Users created in MicroNAS are standard Linux system accounts (`useradd -M -s /usr/sbin/nologin`). Their password is set in both the Linux shadow file (via `smbpasswd`) and the WebDAV htpasswd file automatically.
+
+**Rename** — the Rename button in the Users tab renames the Linux account (`usermod -l`). Because SMB and WebDAV store passwords by username, those entries are removed and must be reset after a rename. The UI shows a warning prompt.
+
+**Delete** — removes the Linux account, SMB entry, and WebDAV htpasswd entry.
+
+**Password change** — updates SMB and WebDAV passwords in sync. Changing a user's password also re-registers them in WebDAV if they were created before WebDAV was installed.
 
 ---