Document --setup-repo and --updateHEADmaster

Add a Repository setup and refresh section to README covering the two
modes, SBO_RSYNC_URL, SBO_PERSONAL_TREES, and shadow self-healing.
Extend CLAUDE.md's architecture list with the tree-lifecycle functions,
the CONFIG-block description, and the verified-status notes for the
untested rsync/git/shadow paths.

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

1 files changed, 45 insertions, 10 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 139c896..9983392 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -53,7 +53,12 @@ Top-to-bottom layout:
    `CHROOT_LOCATION=/tmp LOG_ROOT PKG_CACHE='' VERSION=15.0`, sources the config
    if present
    (NOT an error if missing, so the script stays sourceable by `test-logic.sh`),
-   then derives `MIRROR_TREE`. `require_config` (called by `validate_env` and
+   then derives `MIRROR_TREE`. Also sets `SBO_RSYNC_URL` (empty default; rsync
+   source for the SBo tree itself, e.g. `slackbuilds.org::slackbuilds/15.0`,
+   the same source `sbopkg` uses, distinct from the NFS `LOCAL_MIRROR_15` which
+   is a package source only) and `SBO_PERSONAL_TREES` (empty bash associative
+   array; personal-subtree-dir-name -> git clone URL, cloned under
+   `SBO_TREE_ROOTS[0]`). `require_config` (called by `validate_env` and
    `init_base`) is what hard-fails a real run when the config is absent or has
    not set the required paths. `LOCAL_MIRROR_15` is the NFS mountpoint; the tree
    is one level down, `MIRROR_TREE="$LOCAL_MIRROR_15/slackware64-$VERSION"`
@@ -77,10 +82,24 @@ Top-to-bottom layout:
 6. **Dependency resolution** - `resolve_target` -> `_resolve_visit` (DFS topo
    sort + cycle detection). Outputs `RESOLVED_ORDER[]`, records `UNMET[]`,
    `CYCLES[]`, `HAS_README[]`. `installed_in_base` checks base package db.
-7. **Overlay lifecycle** - `setup_overlay` (echoes tmpdir, mounts overlay +
+7. **SBo tree lifecycle (`--setup-repo` / `--update`)** - `rsync_excludes`
+   (echoes one anchored `--exclude=/<dir>/` per `SBO_PERSONAL_TREES` key, the
+   safety invariant that keeps `rsync --delete` from ever touching a personal
+   clone), `rsync_tree` (runs the actual rsync from `SBO_RSYNC_URL` into the
+   tree root with those excludes applied), `collect_shadows` (read-only scan:
+   for each personal-subtree package, finds same-named upstream dirs elsewhere
+   in the tree), `shadow_scan` (prints `collect_shadows` output, confirms
+   interactively, then `rm -r`'s the confirmed set), `setup_repo` (`--setup-repo`
+   entry point: root check, confirm, `rm -rf` the tree root, `rsync_tree`, clone
+   each `SBO_PERSONAL_TREES` subtree, `shadow_scan`, exit; hard-fails on
+   rsync/clone error), `update_personal_trees` (`--update` entry point, runs
+   inline before a build: `rsync_tree` with `--delete` to refresh upstream and
+   undo prior shadows, `git pull` each personal subtree, `shadow_scan` again;
+   fail-soft, warns and continues on any network/git error).
+8. **Overlay lifecycle** - `setup_overlay` (echoes tmpdir, mounts overlay +
    binds), `teardown_overlay` (idempotent, correct reverse order), `cleanup_trap`
    (EXIT/INT/TERM, unwinds all live overlays).
-8. **build_one** - copies SlackBuild into overlay, runs download/md5/build/
+9. **build_one** - copies SlackBuild into overlay, runs download/md5/build/
    installpkg INSIDE the chroot non-interactively via heredoc, reads back a
    status token file, sets status maps. Logs resolved .info env up front and
    the installed file list (from /var/log/packages) after installpkg, so the
@@ -92,11 +111,13 @@ Top-to-bottom layout:
    echoed to the screen (indented) as well as the log, so problems are easy to
    catch. Called while the overlay is still mounted so the host path to the .txz
    is reachable; no cache dependency.
-9. **run_target** - fresh overlay per target, builds resolved chain in order,
-   marks `BLOCKED-BY-DEP` on dependents of failures, tears down.
-10. **print_summary** - color screen recap + plain `summary.log`.
-11. **main** - parse, validate, make `RUN_DIR`, update base, collect targets
-    (single-package or category-folder), run each.
+10. **run_target** - fresh overlay per target, builds resolved chain in order,
+    marks `BLOCKED-BY-DEP` on dependents of failures, tears down.
+11. **print_summary** - color screen recap + plain `summary.log`.
+12. **main** - parse; `--setup-repo` runs and exits before `validate_env`
+    (mirrors `--init-base`); `validate_env`; `--update` runs right after
+    (`update_personal_trees`, before `update_base`); make `RUN_DIR`, update
+    base, collect targets (single-package or category-folder), run each.
 
 ## Teardown order (do not reorder)
 
@@ -116,8 +137,12 @@ recorded separately as a reminder flag, not a status.
 - **Verified by self-check** (`test-logic.sh` in repo, `bash test-logic.sh`, no
   VM needed): topo order, `%README%` recording, unmet-dep, cycle detection, and
   BLOCKED-BY-DEP propagation (`depends_on_failed`, including the transitive
-  one-hop cascade), and the package-cache logic
-  (`cache_decision`/`cache_path`/`cache_store`/`version_of`). The check builds a
+  one-hop cascade), the package-cache logic
+  (`cache_decision`/`cache_path`/`cache_store`/`version_of`), and the SBo
+  tree-lifecycle helpers `rsync_excludes` (one anchored `--exclude=/<dir>/` per
+  `SBO_PERSONAL_TREES` key, empty when no personal trees) and `collect_shadows`
+  (finds upstream dups of personal packages, excludes personal-tree paths
+  themselves, ignores packages with no upstream twin). The check builds a
   fake SBo tree and sources the script with
   config overridden AFTER sourcing (sourcing re-runs the CONFIG block, which
   resets the vars to empty defaults and may source the external config, so test
@@ -149,6 +174,16 @@ recorded separately as a reminder flag, not a status.
   target only (cached `imlib2` dep not linted), and left SUCCESS unaffected.
   Pure host I/O against an external tool, no self-check stub (trivial, no branch
   logic beyond the install check).
+- **NOT runnable-tested (repo lifecycle)**: `--setup-repo` and `--update` have
+  not been run against the real rsync source or real personal-tree git remotes
+  on hardware yet, so `rsync_tree`, `setup_repo`, `update_personal_trees`, the
+  `git clone`/`git pull` paths, and the interactive `shadow_scan` confirm/`rm -r`
+  step are unverified end to end. Only the pure logic underneath
+  (`rsync_excludes`, `collect_shadows`) is self-checked. The load-bearing safety
+  invariant, that `rsync_excludes` anchors each personal dir so `rsync --delete`
+  in `rsync_tree` can never wipe a personal clone, is covered by the
+  `rsync_excludes` self-check but has not been exercised against a live rsync
+  run with `--delete`.
 
 ## Known shortcuts (ponytail: comments in source)