From d5884cd8998cbed908c2f919872ca821b126fc0c Mon Sep 17 00:00:00 2001
From: Alexander Wainwright <code@figtree.dev>
Date: Tue, 24 Jun 2025 15:04:50 +1000
Subject: [PATCH] Update readme

---
 README.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 156 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index d986bb3..d1eb3e6 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,164 @@
-locutus
-=======
+# locutus
 
-A utility wrapper for the venerable borg backup.
+*A simple, opinionated wrapper for the venerable **[BorgBackup](https://www.borgbackup.org/)**.*
 
-Usage
------
+## Features
 
-Installation
-------------
+* **Friendlier CLI:** No need to remember  archive names or full repo paths.
+* **Index-based archive access:** Refer to backups by index (most recent is 0), or by name.
+* **Scriptable:** All commands are suitable for cron or other automation.
+* **Transparent:** Directly uses Borg; never hides or obfuscates underlying repo.  Backups can be fully managed by borg directly, made easier by sourcing locutus.rc in your shell.
 
-Requirements
-^^^^^^^^^^^^
+---
 
-Compatibility
--------------
+## Installation
 
-Licence
--------
+Requires Python 3.11+, [BorgBackup](https://www.borgbackup.org/) (CLI), and a UNIX-like OS.
 
-Authors
--------
+### From source
+
+Clone the repo and install with [uv](https://github.com/astral-sh/uv) or pip:
+
+```sh
+git clone https://github.com/figtree-dev/locutus.git
+cd locutus
+uv tool install .
+```
+
+For development/testing:
+
+```sh
+uv venv
+uv source .venv/bin/activate
+uv sync --extra dev
+```
+
+(See `pyproject.toml` for dev dependencies.)
+
+---
+
+## Quick Start
+
+### 1. **Setup your backup environment**
+
+```sh
+locutus init
+```
+
+* Prompts for your repo and passphrase, creates the rc file.
+* Edit `~/.config/locutus/locutus.toml` to set your include/exclude/prune rules.
+
+### 2. **Create a backup**
+
+```sh
+locutus backup
+```
+
+### 3. **List archives**
+
+```sh
+locutus list
+```
+
+* Archives are in chronological order with reverse indexing, such as `1: ...`, `0: ...`.
+
+### 4. **Mount an archive or the entire repo**
+
+```sh
+locutus mount 0 ~/mnt/backup      # mount most recent archive
+locutus mount ~/mnt/backup        # mount all archives
+```
+
+### 5. **Restore files from an archive**
+
+```sh
+locutus restore 0 ~/restore-dir
+```
+
+### 6. **Unmount a mountpoint**
+
+```sh
+locutus umount ~/mnt/backup
+```
+
+---
+
+## Configuration
+
+* Main config: `~/.config/locutus/locutus.toml` (edit by hand, see sample below)
+* Profile/RC:  `~/.config/locutus/locutus.rc` (holds BORG\_REPO and BORG\_PASSPHRASE)
+
+**Sample **`locutus.toml`**:**
+
+```toml
+[includes]
+paths = [
+    "/etc",
+    "/home",
+    "/var/www"
+]
+
+[excludes]
+paths = [
+    "*.cache",
+    "/tmp",
+    "/home/*/Downloads"
+]
+
+[prune]
+keep_last    = 7
+keep_daily   = 7
+keep_weekly  = 4
+keep_monthly = 6
+
+[compact]
+enabled = true
+```
+
+**Sample **`locutus.rc`**:**
+
+```sh
+export BORG_REPO="user@host:/path/to/repo"
+export BORG_PASSPHRASE="your-strong-password"
+```
+
+---
+
+## Development
+
+* Source code: [`src/locutus/`](src/locutus/)
+* Tests: [`test/`](test/)
+* Run tests:
+
+  ```sh
+  uv venv
+  source .venv/bin/activate
+  uv sync --extra dev
+  pytest
+  ```
+* All CLI entry points are in `main.py` with subcommands for each workflow.
+
+---
+
+## Limitations / Roadmap
+
+* Linux/UNIX only (uses Borg and fusermount).
+* No built-in scheduling (use cron/systemd).
+* One config/profile at a time.
+
+---
+
+## License
+
+GPLv3 (see `LICENSE`)
+
+---
+
+## Author
+
+Alexander Wainwright ([code@figtree.dev](mailto:code@figtree.dev))
+
+---
+
+**Pull requests welcome.**
 
-`locutus` was written by `Alexander Wainwright <code@figtree.dev>`_.