diff --git a/README.md b/README.md
index 34a1945..f4b482f 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,109 @@
 # Linux System Administration Scripts
 
-Automate routine tasks: This project provides a collection of Bash scripts to automate common Linux system administration duties. Automating daily sysadmin tasks improves efficiency and consistency by reducing manual repetition and the risk of human error. Each script is designed to be distribution-agnostic, using only standard base utilities (e.g. rsync, tar, awk, grep, netstat/ss, systemctl) available on most Linux systems. All scripts are released under the GNU GPL v3.0 license and include usage information in their headers.
+A collection of Bash scripts for routine Linux system administration:
+backups, log handling, monitoring, user and service management, and package
+updates.
 
-## Included Scripts
+Each script is distribution-agnostic, using only base utilities (`tar`,
+`rsync`, `find`, `awk`, `grep`, `ss`/`netstat`, `systemctl`), carries its
+usage in its header, and is released under the **GNU GPL v3.0**.
 
-- `backup.sh` – Backup Utility: Archive directories into compressed tarballs for backups.
-- `restore.sh` – Restore Utility: Restore files from backup archives.
-- `disk_cleanup.sh` – Disk Usage & Cleanup: Report disk usage and identify large files; optionally clean package caches and temporary files to free space.
-- `log_inspect.sh` – Log Inspection: Search within log files or tail the latest system logs for troubleshooting.
-- `log_rotate.sh` – Log Rotation: Compress and rotate old log files to prevent excessive disk usage
-- `network_info.sh` – Network & Firewall Info: Show network interface details, routing table, open listening ports, and basic firewall (iptables) rules.
-- `process_monitor.sh` – Process Management: List top resource-consuming processes and allow termination of processes by name or PID.
-- `security_audit.sh`– Security Audit: Scan for security issues like world-writable files, SUID/SGID executables, and open network ports.
-- `service_manager.sh`– Service Management: Start, stop, restart, or check status of system services, and enable/disable services at boot.
-- `sys_monitor.sh` – System Monitoring: Display system uptime, resource utilization (CPU, memory, disk), and top processes.
-- `update_system.sh` – System Updates: Apply available package updates and patches (works with apt, yum/dnf, zypper, pacman).
-- `user_manage.sh`  – User and Group Management: Create or remove user accounts and groups, modify user group memberships, and lock/unlock accounts.
-- `zimbra_backup.sh`  - Create a backup for a zimbra mailbox.
-- `zimbra_restore.sh`  - Restore a backup for a zimbra mailbox.
-- `rsync_magic.sh`  -  A smart Bash script that wraps rsync for safe, flexible, and efficient file synchronization and backups.
+## Before you run these
+
+**Most of these run as root and several change or delete things.** They are
+written to be careful about it, but read the header of any script before you
+point it at a system you care about.
+
+The conventions are consistent across the collection:
+
+| | |
+|---|---|
+| `--dry-run` | show what would happen, change nothing |
+| confirmation prompts | anything destructive asks first |
+| `--yes` / `ASSUME_YES=1` / `FORCE=1` | skip the prompt for unattended use |
+| no tty, no override | the script **refuses** rather than proceeding unprompted |
+
+That last row is the important one for cron: a destructive script with no
+terminal to ask on will stop rather than guess.
+
+All fifteen run under `set -euo pipefail`, and the repository is linted by
+ShellCheck on every push.
+
+## The scripts
+
+### Backup and restore
+
+- **`backup.sh`** `<source_dir> <dest_dir>` — archives a directory to
+  `name-backup-YYYYmmdd-HHMMSS.tar.gz`. Refuses to overwrite an existing
+  archive, and writes to a `.partial` name renamed only on success, so an
+  interrupted run cannot leave a truncated file that looks like a backup.
+- **`restore.sh`** `<archive.tar.gz> [target_dir]` — lists the archive
+  contents, confirms, then extracts with `--no-same-owner` and
+  `--no-same-permissions`. An archive chooses its own paths, ownership and
+  modes, so as root those defaults matter.
+- **`rsync_magic.sh`** `[--dry-run] [--inplace] [--yes] <source> <dest>` —
+  rsync wrapper with checksums, ACLs, xattrs and a timestamped backup
+  directory for anything `--delete` removes. Confirms before syncing,
+  because reversing the two arguments erases the backup.
+- **`zimbra_backup.sh`** / **`zimbra_restore.sh`** — per-mailbox Zimbra
+  backup and restore, prompting for address and directory. The backup
+  verifies its own output (size and gzip integrity) rather than trusting a
+  zero exit status, and keeps a failed attempt as `.suspect` for inspection.
+
+### Logs
+
+- **`log_inspect.sh`** `[search <pattern> | tail <logfile>]` — searches
+  `/var/log` or tails a log. Distinguishes "no matches" from "could not read
+  everything", so an unprivileged search does not look like a clean one.
+- **`log_rotate.sh`** `[--days N] [--purge-days N] [--dry-run] [--yes]` —
+  compresses old `.log` files. **Skips files a running process still holds
+  open**, which is why it is not a `logrotate` replacement: it cannot signal
+  daemons or truncate in place, so it leaves those for the real thing.
+  Deleting old archives is opt-in via `--purge-days`.
+
+### Monitoring and inspection
+
+- **`sys_monitor.sh`** — uptime, load, memory, disk, top processes.
+- **`network_info.sh`** — interfaces, routes, listening ports, firewall
+  rules (`iptables`, falling back to `nft`).
+- **`security_audit.sh`** — world-writable files and directories, SUID/SGID
+  binaries, listening ports. Run as root: `find` cannot descend where it may
+  not read, so a clean report as an ordinary user means little.
+- **`disk_cleanup.sh`** `[--clean] [--dry-run] [--age N] [--dirs A,B] [--yes]`
+  — disk usage overview, and optional cleanup of package caches and old temp
+  files. `--dirs` refuses protected system directories and confirms for
+  anything outside `/tmp` and `/var/tmp`.
+
+### System management
+
+- **`process_monitor.sh`** `[kill <name|PID>]` — top consumers; the kill path
+  prints what it matched and asks first, since `pkill` by name can match more
+  than one process.
+- **`service_manager.sh`** `<action> <service>` — start, stop, restart,
+  status, enable, disable, list. `status` and `list` work as any user; the
+  rest require root.
+- **`user_manage.sh`** `<subcommand> …` — add/remove users and groups, group
+  membership, lock/unlock. `listusers` and `listgroups` are open to anyone;
+  everything else needs root. `deluser` removes the home directory, so it
+  shows what will go and confirms.
+- **`update_system.sh`** — detects the package manager (apt, dnf, yum,
+  zypper, pacman) and applies updates unattended. Every branch passes `-y` or
+  `--noconfirm`; on Arch in particular, `-Syuu --noconfirm` answers away the
+  prompts that would otherwise warn about a partial upgrade.
+
+## Contributing
+
+ShellCheck runs on every push and pull request at `warning` severity, against
+a clean tree — anything it reports is new. Run it locally before opening a PR:
+
+```sh
+shellcheck *.sh
+```
+
+Keep the existing conventions: `set -euo pipefail`, a root check on anything
+that changes system state, `--dry-run` where it makes sense, and a
+confirmation plus an unattended escape hatch for anything destructive.
+
+## License
+
+GNU General Public License v3.0 — see [LICENSE](LICENSE).
diff --git a/process_monitor.sh b/process_monitor.sh
index 6dd2025..d6076be 100644
--- a/process_monitor.sh
+++ b/process_monitor.sh
@@ -17,6 +17,8 @@
 # 
 # Usage: process_monitor.sh [kill <process_name|PID>]
 # Description: Without args, shows top CPU & memory processes. With "kill", terminates process by name or PID.
+#   The kill path prints what it matched and asks first -- pkill by name
+#   can match more than one process. Set FORCE=1 to skip the prompt.
 
 set -euo pipefail
 
diff --git a/restore.sh b/restore.sh
index fe5018d..a634d65 100644
--- a/restore.sh
+++ b/restore.sh
@@ -17,6 +17,9 @@
 # 
 # Usage: restore.sh <backup_archive.tar.gz> [target_directory]
 # Description: Extracts the tar.gz archive into the target directory (current dir if not specified).
+#   Lists the archive contents and asks before extracting, since it
+#   overwrites whatever is already there. Set ASSUME_YES=1 to skip the
+#   prompt for unattended use.
 #
 # Extraction options are deliberately conservative -- see the tar call.
 
diff --git a/user_manage.sh b/user_manage.sh
index daf25de..41e9a6a 100644
--- a/user_manage.sh
+++ b/user_manage.sh
@@ -20,7 +20,9 @@
 #                addtogroup <user> <group>, lock <user>, unlock <user>,
 #                listusers, listgroups
 # Description: Automates user/group creation, deletion, and modifications.
-# Requires root privileges for most operations.
+# Requires root for everything except listusers/listgroups.
+# deluser removes the home directory and asks first; set ASSUME_YES=1 to
+# skip that prompt for unattended use.
 
 set -euo pipefail