diff --git a/abra.sh b/abra.sh
index c9d1449..241ef5b 100644
--- a/abra.sh
+++ b/abra.sh
@@ -12,7 +12,35 @@ export PG_BACKUP_VERSION=v2
 export ADMIN_CONFIG_VERSION=v1
 export COMPRESS_STATE_ENTRYPOINT_VERSION=v5
 
+###############################################################################
+# Database maintenance — shrink a bloated Synapse database
+#
 # See https://levans.fr/shrink-synapse-database.html
+#
+# Recommended steps to reclaim disk space:
+#   1. abra app cmd <domain> compress-state run_compressor 500 10000
+#      (compress redundant state — safe while Synapse is running)
+#   2. abra app cmd <domain> db reindex
+#      (rebuild indexes — stop Synapse first)
+#   3. abra app cmd <domain> db vacuum_full
+#      (rewrite tables and reclaim disk — stop Synapse first)
+#
+# Diagnostic commands (safe to run anytime):
+#   abra app cmd <domain> db db_size
+#   abra app cmd <domain> db state_bloat
+#   abra app cmd <domain> db empty_rooms
+#
+# Purge commands (require an admin token):
+#   abra app cmd <domain> app register_admin <user> <pass>
+#   abra app cmd <domain> app get_token <user> <pass>
+#   abra app cmd <domain> app purge_remote_media <days> <token>
+#   abra app cmd <domain> app purge_empty_rooms <token>
+#   abra app cmd <domain> app purge_room <room_id> <token>
+#   abra app cmd <domain> app purge_history <room_id> <days> <token>
+###############################################################################
+
+# --- Diagnostics (db) ---
+
 db_size() {
     echo "=== Database size ==="
     psql -U synapse -d synapse -c "SELECT pg_size_pretty(pg_database_size('synapse')) AS db_size;"
@@ -48,15 +76,8 @@ empty_rooms() {
         );"
 }
 
-reindex() {
-    echo "WARNING: REINDEX locks tables. Synapse should be stopped before running this."
-    echo "Running REINDEX on synapse database..."
-    psql -U synapse -d synapse -c "REINDEX (VERBOSE) DATABASE synapse;"
-    echo "REINDEX complete."
-    psql -U synapse -d synapse -c "SELECT pg_size_pretty(pg_database_size('synapse')) AS db_size;"
-}
+# --- Compression (compress-state) ---
 
-# Run via: abra app cmd <domain> compress-state run_compressor
 run_compressor() {
     CHUNK_SIZE="${1:-${STATE_COMPRESS_CHUNK_SIZE:-500}}"
     CHUNKS="${2:-${STATE_COMPRESS_CHUNKS:-100}}"
@@ -67,6 +88,16 @@ run_compressor() {
         -c "$CHUNK_SIZE" -n "$CHUNKS"
 }
 
+# --- Maintenance (db) — stop Synapse before running these ---
+
+reindex() {
+    echo "WARNING: REINDEX locks tables. Synapse should be stopped before running this."
+    echo "Running REINDEX on synapse database..."
+    psql -U synapse -d synapse -c "REINDEX (VERBOSE) DATABASE synapse;"
+    echo "REINDEX complete."
+    psql -U synapse -d synapse -c "SELECT pg_size_pretty(pg_database_size('synapse')) AS db_size;"
+}
+
 vacuum_full() {
     echo "WARNING: VACUUM FULL locks tables and requires temporary disk space."
     echo "Synapse should be stopped before running this."
@@ -76,8 +107,7 @@ vacuum_full() {
     psql -U synapse -d synapse -c "SELECT pg_size_pretty(pg_database_size('synapse')) AS db_size;"
 }
 
-# Purge commands — run via: abra app cmd <domain> app <command>
-# These use the Synapse admin API and require an admin access token.
+# --- Purge commands (app) — require an admin access token ---
 
 register_admin() {
     USER="${1}"
@@ -184,6 +214,10 @@ for r in data.get('rooms', []):
     echo "Done."
 }
 
+###############################################################################
+# Other commands
+###############################################################################
+
 set_admin () {
     admin=akadmin
     if [ -n "$1" ]