Add --init-base mode for first-time base populate

New --init-base flag installs the full slackware64-15.0 package set into
SLACKWARE_BASE from the mirror, then exits. Runs its own pre-flight checks
(root, NFS reachable, base not under the mirror) since the base does not
exist yet, refuses to clobber a populated base, and seeds the
last-base-update marker so the first build skips a needless re-patch.

Replaces the manual installpkg --root loop that validate_env used to print
as a hint. Docs (README, CLAUDE.md, HANDOFF) updated to match.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

3 files changed, 67 insertions, 14 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 8484a50..d6ee7e9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -49,7 +49,12 @@ Top-to-bottom layout:
    (`ST_STATUS ST_REASON ST_TIME ST_README`), `ACTIVE_MOUNTS[]`.
 3. **usage / init_color / parse_args / validate_env** - fail-fast startup
    checks with copy-pasteable hints.
-4. **update_base** - patches local base from mirror's `patches/packages/` when
+4. **init_base** - `--init-base` mode only. First-time populate: `installpkg
+   --root` the full `slackware64/*/*.t?z` set into `SLACKWARE_BASE`, seed the
+   `last-base-update` marker, exit. Runs its own checks (root, NFS reachable,
+   not under mirror) since the base does not exist yet; refuses to clobber a
+   populated base. Wired in `main` before `validate_env`, exits 0.
+   **update_base** - patches local base from mirror's `patches/packages/` when
    ChangeLog head differs (reused from reference script).
 5. **SBo tree lookup** - `find_slackbuild_dir`, `category_of`, `pkg_key`,
    `read_requires`.
@@ -93,7 +98,8 @@ not a status.
   list `failed` (collides with `depends_on_failed`'s `local -n failed`), and
   `ok`/`bad` must `return 0` (`((x++))` returns nonzero when x was 0).
 - **NOT runnable-tested** (needs the VM): overlay mounts, chroot build flow,
-  base patching, installpkg. Logic mirrors the reference script.
+  base patching, `--init-base` populate, installpkg. Logic mirrors the
+  reference script / the prior manual populate hint.
 
 ## Known shortcuts (ponytail: comments in source)
 
diff --git a/README.md b/README.md
index 03f6964..b29542c 100644
--- a/README.md
+++ b/README.md
@@ -49,16 +49,18 @@ Populate from the NFS mirror with the FULL package set, not a minimal install.
 A minimal base causes false "missing dependency" results that would not happen
 on a normal user's full Slackware install.
 
+Set `SLACKWARE_BASE` and `LOCAL_MIRROR_15` in the script's CONFIG block, then
+run once as root:
+
 ```sh
-mkdir -p /sbo-base/15.0
-for p in /mnt/nfs/slackware64-15.0/slackware64/*/*.t?z; do
-  installpkg --root /sbo-base/15.0 "$p"
-done
+sbo-batch-test --init-base
 ```
 
-Adjust the two paths to your `SLACKWARE_BASE` and `LOCAL_MIRROR_15`. The tool
-will not auto-bootstrap the base unattended; if the base is missing or
-incomplete it fails fast with this exact hint.
+This installs the full `slackware64/*/*.t?z` set into `SLACKWARE_BASE` and
+exits. It refuses to clobber an already-populated base (remove the directory
+first to re-init). The tool will not auto-bootstrap the base during a build; if
+the base is missing or incomplete a build fails fast and points you at
+`--init-base`.
 
 The base is kept patched automatically on each run: when the mirror's
 ChangeLog head differs from the recorded marker, new packages from
@@ -108,6 +110,7 @@ sbo-batch-test --dry-run playwright-cli
 | `--dry-run`       | Resolve and print build order, do not build.                 |
 | `--with-x`        | Enable X passthrough (`xhost +local:hosts`). Headless by default. Security caveat: allows local non-network connections to your X server. |
 | `-j`, `--jobs N`  | Reserved. No-op stub today (builds are serial).              |
+| `--init-base`     | First-time populate `SLACKWARE_BASE` from the mirror, then exit. Run once before the first build. Refuses to clobber an existing base. |
 
 ## Per-package status values
 
diff --git a/sbo-batch-test b/sbo-batch-test
index a06df17..4683eb3 100755
--- a/sbo-batch-test
+++ b/sbo-batch-test
@@ -61,6 +61,7 @@ USE_COLOR=1     # --no-color or non-TTY disables
 DRY_RUN=0       # resolve + print build order, do not build
 WITH_X=0        # --with-x: optional X passthrough (default headless)
 JOBS=1          # -j: reserved, see TODO
+INIT_BASE=0     # --init-base: populate SLACKWARE_BASE from the mirror, then exit
 TARGET_ARG=""
 
 RUN_DIR=""              # timestamped log dir for this run
@@ -98,6 +99,9 @@ OPTIONS:
                    allows local non-network connections to your X server).
                    Default is headless (no X).
   -j, --jobs N     Reserved. Currently a no-op stub (builds are serial).
+  --init-base      First-time populate SLACKWARE_BASE with the FULL 15.0
+                   package set from the mirror, then exit. Run once before the
+                   first build. Refuses to clobber an existing base.
 
 EXTENSION POINTS (not implemented, see TODOs in source):
   - "all" mode (build every package across all SBo roots).
@@ -129,6 +133,7 @@ parse_args() {
       --dry-run) DRY_RUN=1; shift ;;
       --with-x) WITH_X=1; shift ;;
       -j|--jobs) JOBS="${2:-1}"; shift 2 ;;  # TODO: implement parallelism
+      --init-base) INIT_BASE=1; shift ;;
       -*) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
       *)
         if [[ -n "$TARGET_ARG" ]]; then
@@ -138,7 +143,7 @@ parse_args() {
         TARGET_ARG="$1"; shift ;;
     esac
   done
-  if [[ -z "$TARGET_ARG" ]]; then
+  if [[ -z "$TARGET_ARG" && $INIT_BASE -eq 0 ]]; then
     echo "No target given." >&2; usage >&2; exit 2
   fi
 }
@@ -160,10 +165,7 @@ It must be a LOCAL (non-NFS) full Slackware 15.0 install tree.
 Populate it from the mirror with the FULL package set (not minimal,
 a minimal base causes false "missing dependency" results):
 
-  mkdir -p "$SLACKWARE_BASE"
-  for p in "$LOCAL_MIRROR_15"/slackware64/*/*.t?z; do
-    installpkg --root "$SLACKWARE_BASE" "\$p"
-  done
+  $0 --init-base
 EOF
     exit 1
   fi
@@ -198,6 +200,44 @@ EOF
 # keep base patched from the mirror (reuse reference logic, point at NFS mirror,
 # write to local base). Skipped on --dry-run.
 # =============================================================================
+# =============================================================================
+# first-time base populate. --init-base only. Installs the FULL 15.0 package
+# set from the mirror into SLACKWARE_BASE, then exits (caller does not build).
+# Refuses to clobber an already-populated base.
+# =============================================================================
+init_base() {
+  if [[ $EUID -ne 0 ]]; then
+    echo "--init-base must run as root (installpkg --root)." >&2; exit 1
+  fi
+  case "$SLACKWARE_BASE" in
+    "$LOCAL_MIRROR_15"*)
+      echo "SLACKWARE_BASE must NOT live under LOCAL_MIRROR_15 (NFS)." >&2; exit 1 ;;
+  esac
+  if [[ ! -d "$LOCAL_MIRROR_15" || ! -f "$LOCAL_MIRROR_15/ChangeLog.txt" ]]; then
+    echo "LOCAL_MIRROR_15 not reachable (NFS mount absent?): $LOCAL_MIRROR_15" >&2; exit 1
+  fi
+  if [[ -d "$SLACKWARE_BASE/var/log/packages" ]]; then
+    echo "Base already populated: $SLACKWARE_BASE" >&2
+    echo "Remove it first to re-init, or just run a build (update_base keeps it patched)." >&2
+    exit 1
+  fi
+  echo "Populating base from mirror into: $SLACKWARE_BASE"
+  mkdir -p "$SLACKWARE_BASE"
+  local p n=0
+  for p in "$LOCAL_MIRROR_15"/slackware64/*/*.t?z; do
+    [[ -e "$p" ]] || continue
+    installpkg --root "$SLACKWARE_BASE" "$p"
+    ((n++)); ((n % 50 == 0)) && echo "  ...$n packages"
+  done
+  if [[ $n -eq 0 ]]; then
+    echo "No packages found under $LOCAL_MIRROR_15/slackware64/*/. Wrong mirror layout?" >&2
+    exit 1
+  fi
+  # Seed the update marker so the next run does not re-patch needlessly.
+  head -n1 "$LOCAL_MIRROR_15/ChangeLog.txt" > "$SLACKWARE_BASE/last-base-update"
+  echo "Base populated: $n packages installed into $SLACKWARE_BASE"
+}
+
 update_base() {
   local marker="$SLACKWARE_BASE/last-base-update"
   touch "$marker"
@@ -622,6 +662,10 @@ print_summary() {
 main() {
   parse_args "$@"
   init_color
+  if [[ $INIT_BASE -eq 1 ]]; then
+    init_base
+    exit 0
+  fi
   validate_env
 
   RUN_DIR="$LOG_ROOT/$(date +%Y-%m-%d_%H-%M-%S)"