1 files changed, 43 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a485a11
--- /dev/null
+++ b/README.md
@@ -0,0 +1,43 @@
+# mkwheels
+
+Build a reproducible, pinned Python wheels tarball for vendoring into a
+SlackBuild (or any offline `pip install`). Generic over package + version.
+
+## Usage
+
+```
+mkwheels <pkg> <ver> [epoch]
+```
+
+- `<pkg> <ver>` — the PyPI package and exact version to vendor.
+- `[epoch]` — optional `SOURCE_DATE_EPOCH`. Omitted → auto-derived from the
+  PyPI release upload time (a warning is printed). Pass it to override.
+- `OUTPUT` env var overrides the output directory (default: current dir).
+
+Outputs `<pkg>-wheels-<ver>.tar.gz` and `requirements.txt` (pinned + hashed).
+Prints the md5sum and the resolved epoch.
+
+## Requirements
+
+`bash`, `python3` + `pip`, `jq`, `curl`, `tar`, `gzip`, `md5sum`.
+
+## Reproducibility
+
+PyPI releases are immutable, so the wheel set for a fixed version is
+deterministic. The tarball normalizes tar metadata (sorted entries, fixed
+mtime/owner, `gzip -n`) so it is byte-identical for the same inputs + epoch.
+
+Git-sourced dependencies (packages whose upstream pins a git URL) are frozen
+at download time: `pip download` resolves whatever is current, and the emitted
+`requirements.txt` records the exact resolved versions. Once built, the
+tarball is the source of truth.
+
+## SBo integration
+
+Run `mkwheels <pkg> <ver>`, upload the tarball to your package host, and set
+`DOWNLOAD_x86_64` / `MD5SUM_x86_64` in the SlackBuild `.info` to point at it.
+The SlackBuild then `pip install --no-index --find-links=<wheels>` into a venv.
+
+## License
+
+GPLv2 (v2-only). See `LICENSE`. Copyright (C) 2026 Danilo M. <danix@danix.xyz>.