From 2fc26df1e54cf54ec4228572ffc96f66417bde8e Mon Sep 17 00:00:00 2001
From: Peter van Arkel <peter@hippogrief.nl>
Date: Wed, 4 Feb 2026 01:26:01 +0100
Subject: [PATCH] Update readme.md

---
 README.md | 130 +++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 94 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index bcb241b..6a3a5f6 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,112 @@
 # pobsync
 
-`pobsync` is a pull-based backup tool for sysadmins.
-It creates rsync-based snapshots with hardlinking (`--link-dest`) and stores them centrally on a backup server.
+`pobsync` is a pull-based backup tool that runs on a central backup server and pulls data from remote servers via rsync over SSH.
 
-Backups are pulled over SSH, not pushed, and are designed to be run from cron or manually.
+Key points:
 
-* * *
-## Design overview
+- All backup data lives on the backup server.
+- Snapshots are rsync-based and use hardlinking (--link-dest) for space efficiency.
+- Designed for scheduled runs (cron) and manual runs.
+- Minimal external dependencies (currently only PyYAML).
 
-  * Runtime, config, logs and state live under `/opt/pobsync`
-  * Backup data itself is stored under a configurable `backup_root` (e.g. `/srv/backups`)
-  * Two snapshot types:
-    * scheduled
-Participates in retention pruning (daily / weekly / monthly / yearly)
-    * manual
-Kept outside the scheduled prune chain, defaults to hardlinking from the latest scheduled snapshot
-  * Minimal dependencies (currently only `PyYAML`)
-
-* * *
 ## Requirements
 
-  * Python 3.11+
-  * `rsync`
-  * `ssh`
-  * Root or sudo access on the backup server
-  * SSH keys already configured between backup server and remotes
+On the backup server:
 
-* * *
-## Installation (canonical runtime under /opt/pobsync, no venv)
+- Python 3
+- rsync
+- ssh
+- SSH key-based access from the backup server to remotes
 
-This assumes you are installing as root or via sudo.
+## Canonical installation (no venv, repo used only for deployment)
 
-1) Clone the repo
+This project uses a simple and explicit deployment model:
 
-    git clone https://code.hosting.hippogrief.nl/hippogrief/pobsync.git
-    cd pobsync
+- The git clone is only used as a deployment input (and later for updates).
+- Runtime code is deployed into /opt/pobsync/lib.
+- The canonical entrypoint is /opt/pobsync/bin/pobsync.
 
-2) Deploy the runtime into `/opt/pobsync` (copies code into `/opt/pobsync/lib` and installs `/opt/pobsync/bin/pobsync`)
+### Install
 
-    sudo ./scripts/deploy --prefix /opt/pobsync
+```git clone https://code.hosting.hippogrief.nl/hippogrief/pobsync.git
+cd pobsync
+sudo ./scripts/deploy --prefix /opt/pobsync
 
-3) Initialize runtime layout and global config
+pobsync install --backup-root /mnt/backups/pobsync (install default configurations)
+pobsync doctor (check if the installation was done correctly)
+```
 
-    sudo /opt/pobsync/bin/pobsync install --backup-root /mnt/backups/pobsync
-    sudo /opt/pobsync/bin/pobsync doctor
+### Update
 
-## Updating
+```
+cd /path/to/pobsync
+git pull
 
-    cd /path/to/pobsync
-    git pull
-    sudo ./scripts/deploy --prefix /opt/pobsync
-    sudo /opt/pobsync/bin/pobsync doctor
+sudo ./scripts/deploy --prefix /opt/pobsync
+sudo /opt/pobsync/bin/pobsync doctor
+```
 
+## Configuration
+
+Global configuration is stored at:
+
+- /opt/pobsync/config/global.yaml
+
+Per-host configuration files are stored at:
+
+- /opt/pobsync/config/hosts/<host>.yaml
+
+## Some useful commands to get you started
+
+Create a new host configuration:
+
+`pobsync init-host <host>`
+
+List configured remotes:
+
+`pobsync list-remotes`
+
+Inspect the effective configuration for a host:
+
+`pobsync show-config <host>`
+
+## Running backups
+
+Run a scheduled backup for a host:
+
+`pobsync run-scheduled <host>`
+
+Optionally apply retention pruning after the run:
+
+`pobsync run-scheduled <host> --prune`
+
+## Scheduling (cron)
+
+Create a cron schedule (writes into /etc/cron.d/pobsync by default):
+
+`pobsync schedule create <host> --daily 02:15 --prune`
+
+List existing schedules:
+
+`pobsync schedule list`
+
+Remove a schedule:
+
+`pobsync schedule remove <host>`
+
+Cron output is redirected to:
+
+- /var/log/pobsync/<host>.cron.log
+
+## Development (optional)
+
+For development purposes you can still use an editable install, this is why pyproject.toml still exists:
+
+```
+python3 -m pip install -e .
+pobsync --help
+```
+
+For production use, always use the canonical entrypoint:
+
+/opt/pobsync/bin/pobsync