Add README, runbook, per-script docs, CHANGELOG and LICENSE.

Documents the organise-isos and generate-ventoy-json workflow end-to-end: quick start in the README, full procedure with troubleshooting and recovery in docs/RUNBOOK.md, and reference docs for each script covering parameters, parsing rules, category groupings, and extensibility. Ships a YOLO licence (no warranty) and seeds CHANGELOG.md for the v0.1.0 release.
2026-05-21 10:33:10 +01:00 · 2026-05-21 10:33:10 +01:00 · 74b210a702
commit 74b210a702
parent 0c06a1483c
7 changed files with 718 additions and 0 deletions
--- a/docs/directory-layout.md
+++ b/docs/directory-layout.md
@ -0,0 +1,96 @@
+# Directory layout
+
+A description of the on-disk shape these scripts work with — both the local
+working copy and what ends up on the Ventoy USB.
+
+## Local working copy
+
+```
+ventoy-extras/                       # this repo
+├─ organise-isos.ps1
+├─ generate-ventoy-json.ps1
+├─ ventoy.json                       # generated, gitignored — your menu
+├─ iso-library/                      # generated, gitignored — your ISOs
+│  ├─ ubuntu/
+│  │  └─ 24.04/
+│  │     └─ x86_64/
+│  │        └─ ubuntu-24.04.1-desktop-amd64.iso
+│  ├─ debian/
+│  │  └─ 12/
+│  │     └─ x86_64/
+│  │        └─ debian-12.5.0-amd64-netinst.iso
+│  ├─ rocky/
+│  │  └─ 9.3/
+│  │     ├─ x86_64/
+│  │     │  └─ Rocky-9.3-x86_64-minimal.iso
+│  │     └─ aarch64/
+│  │        └─ Rocky-9.3-aarch64-minimal.iso
+│  ├─ proxmox-ve/
+│  │  └─ 8.2/
+│  │     └─ noarch/
+│  │        └─ proxmox-ve_8.2-1.iso
+│  └─ ...
+└─ docs/
+```
+
+You can keep `iso-library/` and `ventoy.json` anywhere — pass `-IsoRoot`
+and `-OutFile` to point at them. Keeping them outside the repo is the
+sensible default for non-trivial ISO collections.
+
+## On the Ventoy USB
+
+```
+E:\                                  # Ventoy data partition root
+├─ ventoy\
+│  ├─ ventoy.json                    # copied from the generated file
+│  ├─ theme\                         # optional, not managed by these scripts
+│  └─ ...                            # other Ventoy config
+├─ iso-library\
+│  ├─ ubuntu\
+│  │  └─ 24.04\
+│  │     └─ x86_64\
+│  │        └─ ubuntu-24.04.1-desktop-amd64.iso
+│  └─ ...
+└─ (anything else you want on the stick)
+```
+
+Ventoy treats the data partition as a regular FAT/exFAT/NTFS filesystem.
+The bootloader lives on a separate hidden ESP partition that these scripts
+do not touch.
+
+## Why three levels (`os/version/arch`)
+
+- **`os/`** — keeps the same OS together regardless of version churn. Easier
+  to clean up when retiring an EOL distro.
+- **`version/`** — lets you have multiple versions of the same OS without
+  filename collisions, and gives Ventoy a clean per-version label.
+- **`arch/`** — multi-arch ISOs (typically x86_64 + aarch64 for RHEL family,
+  Debian, Ubuntu) sort cleanly side by side.
+
+When arch isn't applicable (hypervisor appliances, BSD distros that ship
+multi-arch in one image), the slot becomes `noarch\` and the generator omits
+the `[<arch>]` suffix from menu labels.
+
+## Path constraints
+
+- **Forward vs backslash**: the local Windows paths use `\`. `ventoy.json`
+  paths use `/` (Ventoy is essentially Linux-bootstrapped and expects POSIX
+  paths). The generator handles the translation.
+- **Leading slash**: `ventoy.json` paths start with `/` and are rooted at
+  the **Ventoy data partition root**, not the filesystem root.
+- **Long paths**: deeply-nested distros (`opensuse-tumbleweed/...`) plus
+  long ISO filenames can exceed 260 chars on Windows. PowerShell 7+ handles
+  this transparently; on 5.1 you may need `\\?\` prefixes if you hit it.
+  Robocopy handles long paths regardless of PS version.
+
+## Gitignore recommendation
+
+A `.gitignore` for this repo (not yet committed):
+
+```
+iso-library/
+ventoy.json
+*.iso
+```
+
+ISOs are large and frequently rotated. Don't commit them.