catalogue

added usage and info about it

README.md

@@ -554,15 +554,51 @@ If the same source files are imported again, their hashes will
 already exist in the database and they will be skipped.
 
 
-### BACKUP REMINDER
+# catalogue.py
 
-A single external drive is not a complete backup strategy.
+Read-only HTML catalogue generator for backups created by `o-phone.py`.
 
-If the media is important, maintain at least one additional,
+Produces a single offline `index.html` you can open directly from the backup folder. No web server, no external dependencies, no changes to your media or database.
-independent copy.
 
-A RAID array, external drive, or database does not by itself protect
+## Requirements
-against every form of data loss.
 
-o-phone.py is an organisation and import tool, not a replacement for
+- Python 3.9+
-a complete backup strategy.
+- An existing o-phone backup that contains `.photo_organiser.db`
+
+## Usage
+
+```bash
+# Generate the catalogue
+python3 catalogue.py "/path/to/phone-media-backup"
+
+# Generate and open in your default browser
+python3 catalogue.py "/path/to/phone-media-backup" --open
+
+# Check database ↔ filesystem consistency (no HTML written)
+python3 catalogue.py "/path/to/phone-media-backup" --check
+
+# Extra diagnostic detail
+python3 catalogue.py "/path/to/phone-media-backup" --check --verbose
+```
+
+Output is always written to:
+
+```
+/path/to/phone-media-backup/index.html
+```
+
+## What it shows
+
+- Year → Month → Day layout (newest first)
+- Filter buttons: All / Photos / Videos / Screenshots
+- Client-side search (filename, date, device, type, etc.)
+- Click any item for a lightbox viewer (← → Esc)
+- Videos and screenshots are marked; RAW files show a placeholder
+- Lazy-loaded thumbnails; original files are never modified
+
+## Safety
+
+- Opens the SQLite database **read-only**
+- Never moves, renames, deletes, or copies media
+- Never writes to the database
+- Missing files are reported as warnings; the catalogue is still generated for files that exist