docs: test-build design spec; refine CLAUDE.md purpose and docker workflow

1 files changed, 82 insertions, 12 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 89c86cf..5bfba11 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,10 +1,27 @@
 # SBo SlackBuilds Repository
 
-SlackBuild scripts maintained by Danilo (danix) and submitted to
-[SlackBuilds.org (SBo)](https://slackbuilds.org). This repo holds ONLY the
-packages for which danix is the **official SBo maintainer**. Lead and
-experimental packages not on SBo under danix live in the separate
-`my-slackbuilds` repository.
+SlackBuild scripts for which danix is the **official SBo maintainer** on
+[SlackBuilds.org (SBo)](https://slackbuilds.org).
+
+## Purpose: tracking, not development
+
+This repo is a **maintenance mirror of already-published SBo packages**. No new
+packages are developed here. Its job is the ongoing upkeep of packages already
+on SBo:
+
+1. Track upstream version changes (via nvchecker).
+2. Reflect a new upstream version in the package's `.SlackBuild` / `.info`.
+3. Test-build in a throwaway docker image (see below).
+4. Generate the SBo submission tarball to upload.
+
+New-package development happens in **other** repos, not here:
+
+- `../GITHUB/my-slackbuilds/` — regular packages, plus SBo packages whose
+  upstream moves faster than SBo review (worked ahead of the SBo copy).
+- `../GITHUB/Slackware-Pentesting-Suite/` — cybersecurity packages.
+
+When a new package is uploaded to SBo and approved, it **moves here** and this
+repo takes over its maintenance.
 
 ---
 
@@ -31,7 +48,9 @@ Version tracking is handled by a single file:
 ### `.extras/` holds all non-package repo files
 
 Anything that is not a SlackBuild package must live under `.extras/`, never at
-the repo root.
+the repo root. Exception: a top-level `docs/` for design docs and specs is fine
+in this repo (the subtree-leak concern that bans it applies to the development
+repos, not here). Existing specs live under `.extras/docs/specs/`.
 
 ---
 
@@ -122,9 +141,52 @@ compiled binaries. No stripping needed.
 
 ---
 
+## Test-building in docker
+
+Because these packages are already published on SBo, the build here is a
+**verification step** on a version bump, not development. It runs in a
+throwaway Slackware container, so it is hermetic and disposable: unlike a real
+`slackrepo build` on the buildsystem VM, **Claude may run it directly**.
+
+Images (Slackware official, pull fresh each time — they are throwaway):
+
+- `-current`: `registry.slackware.nl/slackware/slackware-builder:current`
+- `15.0` (stable): `registry.slackware.nl/slackware/slackware-builder:15.0`
+
+Mount the package dir into a `--rm` container and run its SlackBuild. Anything
+built is discarded with the container; nothing lands in the working tree.
+
+No wrapper script exists yet — write the `docker run` invocation inline, or add
+one under `.extras/` if this gets repetitive. The build's only outputs that
+matter are the exit status and lint result; the package tarball it produces is
+throwaway.
+
+The one artifact worth keeping from a clean bump is the **SBo submission
+tarball** (`SBo/<pkg>.tar.gz`), produced by the `post-commit` hook — that is
+what gets uploaded to SlackBuilds.org.
+
+---
+
 ## SlackBuild Scripting Guidelines
 
-- Follow the [SBo template](https://slackbuilds.org/templates/) as the base for all scripts
+### Templates (local clone)
+
+A clone of the SBo templates lives at `~/Templates/SlackBuilds/sbo/` (refreshed
+by `~/Templates/SlackBuilds/update-templates.sh`). **Start from the matching
+file there** rather than from memory:
+
+- Per-build-type SlackBuilds: `autotools-`, `cmake-`, `meson-`, `python-`,
+  `perl-`, `rubygem-`, `haskell-template.SlackBuild`.
+- Shared support files: `slack-desc`, `template.info`, `doinst.sh`,
+  `douninst.sh`.
+
+The [online SBo template](https://slackbuilds.org/templates/) remains the
+authority; the local clone mirrors it. Refresh the clone if it looks stale
+before relying on it.
+
+### General
+
+- Follow the SBo template (local clone above) as the base for all scripts
 - Use `set -e` to abort on errors
 - Honor `$TMP`, `$BUILD`, `$TAG`, `$OUTPUT` variables; default values must be set if unset
 - Use `$ARCH` detection with proper `SLKCFLAGS` and `LIBDIRSUFFIX`
@@ -215,11 +277,19 @@ be committed.
 
 ## Who builds SlackBuilds
 
-Only the user builds SlackBuilds, on their own infra. Claude authors/edits the
-sources (`.SlackBuild`, `.info`, `README`, `slack-desc`, `doinst.sh`, nvchecker
-stanzas) and runs only the non-building checks (`sbolint`, `sbodl`,
-`sbofixinfo`); the user builds and reports back. Never run or offer
-`bash <pkg>.SlackBuild`, `sbopkglint`, or `slackrepo build`.
+Claude authors/edits the sources (`.SlackBuild`, `.info`, `README`,
+`slack-desc`, `doinst.sh`, nvchecker stanzas) and runs the non-building checks
+(`sbolint`, `sbodl`, `sbofixinfo`).
+
+**The one exception in this repo** is the throwaway-docker test-build (see
+[Test-building in docker](#test-building-in-docker)): it is hermetic and
+disposable, so Claude may run it to verify a bump, including `sbopkglint` on
+the throwaway package it produces.
+
+Everything else stays with the user: never run or offer a **real**, persistent
+build — `slackrepo build`, or `bash <pkg>.SlackBuild` / `sudo bash ...` on the
+host (as opposed to inside the throwaway container). Those install to the
+user's system or the buildsystem VM; the user runs them and reports back.
 
 ---