Document package cache (CLAUDE.md, README)

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

2 files changed, 30 insertions, 10 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 1254ab1..4630cb4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -50,7 +50,8 @@ Top-to-bottom layout:
    `~/.config/sbo-batch-tester/config`, i.e. `/root/.config/...` since it runs
    as root); `config.example` in the repo is the template. The block sets empty
    defaults (`SLACKWARE_BASE LOCAL_MIRROR_15 SBO_TREE_ROOTS`) plus
-   `CHROOT_LOCATION=/tmp LOG_ROOT VERSION=15.0`, sources the config if present
+   `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
    `init_base`) is what hard-fails a real run when the config is absent or has
@@ -98,16 +99,19 @@ so a mid-target abort still unwinds. `ACTIVE_MOUNTS[]` tracks live overlays.
 
 ## Status values
 
-`SUCCESS DOWNLOAD-FAILED MD5-MISMATCH BUILD-FAILED INSTALL-FAILED
-BLOCKED-BY-DEP UNMET-DEP`. `%README%` recorded separately as a reminder flag,
-not a status.
+`SUCCESS CACHED DOWNLOAD-FAILED MD5-MISMATCH BUILD-FAILED INSTALL-FAILED
+BLOCKED-BY-DEP UNMET-DEP`. `CACHED` = a dependency installed from the persistent
+package cache instead of being rebuilt (target is never CACHED). `%README%`
+recorded separately as a reminder flag, not a status.
 
 ## What is verified vs not
 
 - **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). The check builds a fake SBo tree and sources the script with
+  one-hop cascade), and the package-cache logic
+  (`cache_decision`/`cache_path`/`cache_store`/`version_of`). 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
   vars must be set after the `source`). The test runs as a normal user, so
@@ -137,11 +141,13 @@ not a status.
   resolved `.info` env, and the installed file list, so the overlay holds
   nothing worth retaining. Do not re-add `--keep` without a reason logs cannot
   cover.
-- **Package-output cache** (deferred, user wants it next): keep built `.tgz`
-  outside the overlay, `installpkg` a cached dep instead of rebuilding. Fixes
-  the "shared deps rebuilt per target" cost in category mode. Likely shape: a
-  per-run stash in `$RUN_DIR/pkgcache` keyed `prog-version`, reused across
-  targets within one run. NOT implemented yet.
+- **Package cache (DONE).** Persistent `$PKG_CACHE` (config var, empty =
+  disabled), SBo-tree layout `<cat>/<prog>/<prog>-<ver>-...txz`, one .txz per
+  prog. Key = prog+version (build/arch/tag ignored). The named target always
+  builds fresh and refreshes the cache; deps install from cache on a version
+  match (status `CACHED`), else build and cache. Cache wiped when `update_base`
+  patches. Pure `cache_decision`/`cache_path`/`cache_store`/`version_of` covered
+  by `test-logic.sh`. Spec: docs/superpowers/specs/2026-06-24-package-cache-design.md.
 - **"all" mode**: build every package across all SBo roots. Extension point in
   `main` where `targets` is populated. TODO marker in source.
 - **queue/list-file mode**: build a named list. Same extension point.
diff --git a/README.md b/README.md
index 6a15ff0..8f32ead 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,20 @@ The base is kept patched automatically on each run: when the mirror's
 ChangeLog head differs from the recorded marker, new packages from
 `patches/packages/` are applied to the local base via `upgradepkg`.
 
+## Package cache
+
+Set `PKG_CACHE` in your config to a local directory to cache built packages
+across runs (leave empty to disable). Layout mirrors the SBo tree
+(`<category>/<prog>/<prog>-<version>-...txz`), one package per prog.
+
+The named target always builds fresh, it is the package under test. Its
+dependencies are installed from the cache when their version is unchanged
+(reported as `CACHED`), otherwise they are built and cached. A build order line
+shows the outcome per package: `cached (1.1)`, `rebuild: 1.0 -> 1.1`, or
+`build (new)`; `--dry-run` shows the same without building. The whole cache is
+wiped automatically when the base is patched, since cached packages were built
+against the previous base.
+
 ## Usage
 
 ```