diff --git a/README.md b/README.md
new file mode 100644
index 0000000..65eaeba
--- /dev/null
+++ b/README.md
@@ -0,0 +1,90 @@
+# sysinfo
+
+**sysinfo** captures a point-in-time snapshot of block devices, ZFS pools,
+network interfaces, sensors, installed packages, and other host metadata.
+It writes a structured tree to `/etc/sysinfo/` and also produces a single
+JSON document.
+
+* Repository  <https://git.eeqj.de/sneak/sysinfo>  
+
+* License  [WTFPL](https://www.wtfpl.net/)  
+
+* Author  sneak — <sneak@sneak.berlin>
+
+---
+
+## Quick install & run (Go 1.22 or newer)
+
+```console
+# install the latest tagged build into $GOBIN
+go install git.eeqj.de/sneak/sysinfo/cmd/sysinfo@latest
+
+# generate a snapshot
+sudo sysinfo
+```
+
+Check the embedded version string:
+
+```console
+sysinfo --version
+```
+
+---
+
+## Typical usage
+
+```console
+sudo sysinfo                 # write /etc/sysinfo + snapshot.json
+sudo sysinfo --force         # overwrite existing snapshot
+sudo sysinfo --json > out.json   # JSON to stdout only
+```
+
+* On first run, required utilities (e.g. `smartctl`, `zfsutils-linux`,
+  `lm-sensors`) are installed automatically via **apt-get** with
+  `DEBIAN_FRONTEND=noninteractive`.
+* Collectors run only when their prerequisites are met (e.g. the ZFS
+  collector runs only if `zpool` is present).
+* Only ubuntu is supported for now.
+
+---
+
+## Building from source
+
+```console
+git clone https://git.eeqj.de/sneak/sysinfo.git
+cd sysinfo
+make build      # builds ./sysinfo with embedded version
+sudo ./sysinfo
+```
+
+`make install` installs the tool to `$GOBIN`.
+
+---
+
+## Snapshot layout (example)
+
+```
+/etc/sysinfo/
+├── snapshot.json
+├── system/
+├── blockdevs/
+├── network/
+├── sensors/
+├── packages/
+└── zfs/
+```
+
+`snapshot.json` contains the same data flattened into a single file; the
+directories mirror the JSON hierarchy for easy inspection.
+
+---
+
+## Notes
+
+* Developed and tested on Ubuntu 22.04+. Additional distros can be
+  supported by implementing new `PackageManager` back-ends.
+* No telemetry or external network access is performed other than an
+  IP geolocation lookup (`curl https://ipinfo.io`) on default
+  interfaces.
+
+PRs and patches are welcome.