Document direct executable downloads and Unix permissions (bench 5551733)

Co-authored-by: GPT-6 Astra <codex@openai.com>

README.md

@@ -29,8 +29,8 @@ Heimdall is a strong chess engine written in Nim. As far as I know, this is the
 ### How to pick the right executable
 
 Fetching the latest stable release is the easiest way to install Heimdall. For
-current releases after **1.5**, choose the archive for your operating system.
-Universal builds select the supported SIMD backend automatically.
+current releases after **1.5**, choose the executable or archive for your
+operating system. Universal builds select the supported SIMD backend automatically.
 
 | Your computer | Archive filename ends with |
 | --- | --- |
@@ -43,6 +43,17 @@ the [latest release](https://git.nocturn9x.space/nocturn9x/heimdall/releases),
 extract it, and select the executable in your chess GUI. All builds require a
 64-bit system; the macOS build requires macOS 11 or later.
 
+You can also download the executable directly from the same release, without
+the `.zip` or `.tar.gz` archive. On Linux and macOS, direct downloads may need
+execute permission before you can run them or select them in a chess GUI:
+
+```sh
+chmod +x /path/to/downloaded/heimdall-executable
+```
+
+Replace the path with your downloaded filename. On Windows, download the `.exe`
+file directly; no `chmod` step is needed.
+
 The Linux executable selects AMD64 or ARM64 and extracts its engine and shared
 network into a private runtime cache on first launch. See the
 [cache requirements and settings](docs/RELEASES.md#linux-universal-executable).
@@ -54,8 +65,9 @@ the standalone download for your CPU:**
 - **ARM64 / AArch64:** `linux-arm64-universal.tar.gz`
 
 Both fallbacks are included in automatic releases, embed their network weights,
-and need no launcher or runtime cache. Extract the matching archive and select
-its executable in your chess GUI.
+and need no launcher or runtime cache. Extract the matching archive or download
+its executable directly, set execute permission if needed, and select it in your
+chess GUI.
 
 For source builds, platform-specific binaries, testing, and release details,
 see the [building guide](docs/BUILDING.md). The [testing guide](docs/TESTING.md)

docs/BUILDING.md

@@ -2,7 +2,21 @@
 
 The latest stable release is the easiest way to install Heimdall. See the
 [download table in the README](../README.md#how-to-pick-the-right-executable)
-for the universal archive that matches your system.
+for the universal download that matches your system.
+
+Each release offers executables directly as well as `.tar.gz` archives
+(Linux/macOS) or `.zip` archives (Windows). Extract an archive, or download the
+executable itself. On Linux and macOS, direct downloads may need execute
+permission:
+
+```sh
+chmod +x /path/to/downloaded/heimdall-executable
+```
+
+Use the actual downloaded filename, then run it or select it in your chess GUI.
+On Windows, the direct download is the `.exe` file and needs no `chmod` step.
+See [Linux release requirements](RELEASES.md#linux-universal-executable) for the
+combined executable's runtime cache and standalone fallbacks.
 
 ## Requirements
 

docs/RELEASES.md

@@ -36,17 +36,25 @@ The AMD64 engine retains runtime x86 SIMD selection; ARM64 selects scalar or NEO
 Linux ELF files specify one machine architecture, so the shell launcher chooses
 and extracts the native engine before executing it. This does not use emulation.
 
-Download the `.tar.gz` archive, extract it and select the executable in your chess
-GUI. The executable can be moved or symlinked by itself. It requires `/bin/sh`,
-`gzip` and GNU coreutils (`uname`, `readlink`, `dd`, `sha256sum`, `stat`, `id`,
+Download the executable directly, or extract it from the `.tar.gz` archive.
+A direct download may need execute permission before it can run:
+
+```sh
+chmod +x heimdall-VERSION-linux-universal
+```
+
+Replace `VERSION` with the downloaded filename's version, then select the
+executable in your chess GUI. The executable can be moved or symlinked by itself.
+It requires `/bin/sh`, `gzip` and GNU coreutils (`uname`, `readlink`, `dd`, `sha256sum`, `stat`, `id`,
 `mkdir`, `mktemp`, `chmod`, `mv`, `rm`). The engines retain their normal Linux
 library requirements. A GUI must accept executable scripts.
 
 If the combined executable fails to start or does not work in your chess GUI,
 download `linux-amd64-universal.tar.gz` for Intel/AMD x86-64 or
-`linux-arm64-universal.tar.gz` for ARM64/AArch64 from the same release. Extract
-the archive and select its native executable in the GUI. These fallbacks embed
-their weights, require no launcher or runtime cache, and are included in
+`linux-arm64-universal.tar.gz` for ARM64/AArch64 from the same release, or download
+the matching executable directly. Extract the archive or set execute permission
+on the direct download, then select its native executable in the GUI. These
+fallbacks embed their weights, require no launcher or runtime cache, and are included in
 automatic releases. They can also be selected individually in the workflow.
 
 On first launch, the executable extracts only the selected engine and shared
@@ -118,7 +126,10 @@ Pass custom network/architecture settings through Make's environment, for exampl
 No cross-compiler is needed. Test the resulting executable on both CPU families.
 
 The release publishes the executable, its `<executable>.sha256`, and a `.tar.gz`
-archive containing both. After extracting, run `sha256sum -c <executable>.sha256`.
+archive containing both. For direct downloads, download the checksum file as well
+and run `sha256sum -c <executable>.sha256` in their directory. The same check works
+after extracting the archive. Setting execute permission does not change the
+file's checksum.
 The self-extracting file is deterministic for identical inputs and packaging
 Python/zlib versions; the outer download archive retains normal release metadata.
 
@@ -211,6 +222,9 @@ secrets. If the tag has no release record yet, the existing publisher creates on
 stable versions start as drafts, while alpha/beta/rc/dev releases are prereleases.
 Each target owns three uniquely named files: its executable, an executable-name
 `.sha256` file, and a `.tar.gz` archive (`.zip` on Windows) containing both.
+Users can download the executable directly instead of the archive. On Linux and
+macOS they may need `chmod +x /path/to/downloaded/executable`; on Windows they
+download the `.exe` file directly. All formats contain the same executable.
 Checksums are per executable so one target cannot overwrite another target's manifest.
 
 For a local check using existing dependencies and weights: