initial commit: docker test-build toolchain

Extracted from the .extras/ dir of the sbo-slackbuilds package repo, where it
grew from a throwaway helper into a standalone tool. Git history starts fresh;
the original 41-commit development log is preserved in HISTORY.md.

Contents: the test-build CLI (resolves a local SlackBuild's deps from a
configured SBo tree and builds it in a throwaway container, lints, caches deps),
the image-builder chain that produces the images it consumes, their pure-logic
self-checks, design specs/plans, an install.sh for ~/bin, and docs.

Licensed GPLv2-only.

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

1 files changed, 85 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c52d4d2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# sbo-dockerbuild
+
+Docker-based toolchain for test-building SlackBuilds.org (SBo) packages on
+Slackware, on both `-current` and `15.0`, without touching a real system.
+
+Two tools that share the same set of images:
+
+- **`test-build`** — verify a SlackBuild (the one you are editing, wherever it
+  lives) builds cleanly in a throwaway container. Resolves and builds its SBo
+  deps from a configured tree, caches built deps per image digest, lints the
+  target with `sbopkglint`, and reports per-package status.
+- **`image-builder/`** — build the images `test-build` consumes
+  (`sbo-base` → `sbo-full` → `sbo-testbuild`, per Slackware version) from a
+  mirror of the Slackware package trees, pushed to a LAN registry.
+
+This started as a helper under `.extras/` in the **sbo-slackbuilds** package
+repository and was extracted here to be maintained on its own. See
+[HISTORY.md](HISTORY.md) for the original development log.
+
+## Layout
+
+```
+test-build                 the test-build tool
+test-logic.sh              pure-logic self-check for test-build (no docker)
+test-build-config.example  copy to ~/.config/sbo-testbuild/config and edit
+overrides.example          current-vs-stable dep overrides (optional)
+image-builder/             the image-build scripts + their self-check
+docs/specs, docs/plans     design specs and implementation plans
+```
+
+## Install
+
+Copy the `test-build` CLI into `~/bin` (on your `$PATH`):
+
+```bash
+./install.sh                     # -> ~/bin/test-build
+BINDIR=/usr/local/bin ./install.sh
+./install.sh --uninstall
+```
+
+It copies the file, so re-run after editing `test-build`. The `image-builder/`
+scripts are not installed; they run on the docker host from their own checkout.
+
+## Quick start
+
+Test-build a package you are editing (from its dir, or by path):
+
+```bash
+cd some-slackbuild-dir && test-build <name>        # -current
+test-build --stable <name>                         # 15.0
+test-build --keep <name>                           # also keep the built .txz
+```
+
+Build the images (on the docker host; see `image-builder/README`):
+
+```bash
+cd image-builder
+./bootstrap.sh           --version current --force
+./build-full-image.sh    --version current --force
+./build-sbo-testbuild.sh --version current --force
+```
+
+## Requirements
+
+- Docker with a reachable LAN registry for the built images.
+- A local mirror of the Slackware package tree(s) for the image build, and a
+  checkout of the SBo tree(s) for dependency resolution.
+- `sbo-maintainer-tools` (baked into the images for `sbopkglint`).
+
+See the specs under `docs/specs/` for the full design.
+
+## License
+
+Released under the GNU General Public License, version 2 (v2 only). See
+[LICENSE](LICENSE). Each source file carries a short header notice.
+
+Copyright (C) 2026 Danilo M. &lt;danix@danix.xyz&gt;
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.