From e85d816ed4d6799b83abc3f488b999c5ab44719c Mon Sep 17 00:00:00 2001
From: "russell@unturf.com" <russell@unturf.com>
Date: Mon, 27 Apr 2026 14:04:25 -0400
Subject: [PATCH] README: per-platform clone + install instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a "Get the source" section with the GitLab SSH + HTTPS clone
URLs, then platform-specific prerequisite blocks:

- macOS: Xcode CLT for git/make, Homebrew for python@3.12
- Ubuntu/Debian: apt install python3/python3-venv/build-essential
  /curl/bzip2; 22.04 has 3.10, 24.04 has 3.12
- Windows: WSL2 Ubuntu-24.04 is the supported path. Native cmd
  + Git Bash mostly works for Python but several make targets call
  bash idioms. `wsl --install -d Ubuntu-24.04` from an admin shell.
- OpenBSD: pkg_add git python-3.12 gmake curl. Default `make` is
  BSD make; the project uses GNU-make features so substitute
  `gmake` everywhere.

Bootstrap step (make bootstrap) is unchanged — it stays at the end
of the Setup section once the platform prereqs are in place.
---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 56 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a23da89..97cae66 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,62 @@ After the last command, a Hermes-3 inference runs against the local corpus, pick
 
 ## Setup
 
-Requirements: Python 3.10+, `bzip2`, `curl`, `make`. SQLite 3.35+ (CPython's bundled sqlite3 is fine).
+### Get the source
+
+```
+git clone ssh://git@git.unturf.com:2222/engineering/unturf/aborist.git
+cd aborist
+```
+
+HTTPS variant if SSH isn't set up:
+
+```
+git clone https://git.unturf.com/engineering/unturf/aborist.git
+```
+
+### Install prerequisites
+
+Aborist needs Python 3.10+, GNU make, `curl`, and `bzip2`. SQLite 3.35+ ships with CPython.
+
+**macOS** (Homebrew)
+
+```
+xcode-select --install        # if you don't already have CLT
+brew install python@3.12 git make
+```
+
+Apple's `make` is GNU make, no extra step needed. `bzip2` and `curl` are bundled.
+
+**Ubuntu / Debian**
+
+```
+sudo apt update
+sudo apt install -y git python3 python3-venv python3-dev build-essential curl bzip2
+```
+
+22.04 ships Python 3.10; 24.04 ships 3.12 — both work.
+
+**Windows**
+
+The Makefile uses bash idioms, so the supported path is **WSL2** running Ubuntu. From an admin PowerShell:
+
+```
+wsl --install -d Ubuntu-24.04
+```
+
+Then inside the WSL Ubuntu shell, follow the Ubuntu instructions above.
+
+(Native cmd / PowerShell + Git Bash mostly works for the Python parts but several `make` targets call `for i in $(seq…)` and `bash -c` — easier to just use WSL2.)
+
+**OpenBSD**
+
+```
+pkg_add git python-3.12 gmake curl
+```
+
+OpenBSD's default `make` is BSD make. Aborist's Makefile uses GNU-make features (`?=`, conditional functions). Substitute `gmake` for `make` in every command, e.g. `gmake bootstrap`, `gmake query Q='…'`.
+
+### Bootstrap
 
 ```
 make bootstrap