From 30dbe8eb404564b4ed640a66c1065d5c1ff9f453 Mon Sep 17 00:00:00 2001
From: Lord Race <race@rmf44.xyz>
Date: Wed, 12 Aug 2026 00:15:32 -0500
Subject: [PATCH] docs: replace auto-generated README with project README

---
 README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 78 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e390147..21f907d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,80 @@
 # workspace-ageout
 
-Hot-to-cold tiering changelog for workspace.rmf44.xyz
\ No newline at end of file
+Hot-to-cold tiering changelog for `workspace.rmf44.xyz`.
+
+## What this is
+
+`workspace.rmf44.xyz` lives on `hawker` (VPS, 237 GB root disk) with user files
+stored in `/var/lib/workspace-hot/`. A nightly job ages out files unmodified for
+more than 90 days, moving them to dessert NFS at `/mnt/dessert-cold/` (the
+durability tier). An hourly disk-pressure safety valve does the same when free
+space on hawker drops below 50 GB.
+
+Every aging-out run writes a `changelog/YYYY-MM-DD.txt` entry and commits it to
+this repo, so you have a permanent record of what moved where.
+
+## Restoring an aged-out file
+
+Files aged out of the hot tier are NOT deleted — they live on the cold tier
+(NFS) on `desslok` at `/slab/container_storage/workspace-cold/`. To restore a
+file:
+
+```bash
+# on hawker, as tigo:
+ssh desslok 'ls -la /slab/container_storage/workspace-cold/path/to/file'
+scp desslok:/slab/container_storage/workspace-cold/path/to/file \
+    /var/lib/workspace-hot/path/to/file
+```
+
+Replace `path/to/file` with the relative path shown in the changelog.
+
+## Reading the changelog
+
+```bash
+git log --stat     # overview
+git show HEAD      # most recent run
+ls changelog/      # all dated entries
+```
+
+Each entry looks like:
+
+```
+workspace-ageout run: 2026-08-12T03:00:07Z
+Threshold: 90 days
+
+Disk before: 184G free
+Disk after:  187G free
+Reclaimed:   3G
+
+Files aged out: 47
+  race/files/Projects/old-quarterly-report.docx
+  race/files/Photos/2025/IMG_4401.jpg
+  ...
+
+Files failed: 0
+```
+
+## How it works
+
+- **`/usr/local/bin/workspace-ageout.sh`** runs nightly (cron `0 3 * * *`).
+  Finds files in `/var/lib/workspace-hot/` with `mtime > 90 days`, rsyncs each
+  to `/mnt/dessert-cold/` (preserving relative paths), verifies via md5sum, and
+  deletes from hot. Appdata is excluded.
+
+- **`/usr/local/bin/workspace-pressure.sh`** runs hourly (cron `0 * * * *`).
+  When `df -BG` on hot shows < 50 GB free, ages out oldest files until 80 GB
+  free, regardless of mtime.
+
+Both scripts use a `rsync --remove-source-files`-style two-phase move (rsync
+first, then delete) so a network blip never causes data loss.
+
+## Where data lives
+
+- **Hot tier:** `/var/lib/workspace-hot/` on hawker (local disk)
+- **Cold tier:** `/mnt/dessert-cold/` on hawker → `desslok:/slab/container_storage/workspace-cold/` over NetBird NFS
+- **Changelog:** this repo (auto-committed per run)
+- **Logs:** syslog via `logger -t workspace-ageout` and `logger -t workspace-pressure`
+
+## Restore UX (per Lord Race, 2026-08-11)
+
+User SSHes to hawker and runs `scp` from desslok. No custom tooling, no plugin.