docs: add r8125 build notes and clean-sweep recording step

Fold the r8125 maintainer notes into AGENTS.md rather than a file beside
the package: the post-commit hook tars every file under a package dir into
the SBo submission archive, so notes kept there would ship upstream.

The r8125 section covers what the SlackBuild alone does not explain: the
KERNEL= and PRINT_PACKAGE_NAME=1 overrides, the @KERNEL@ placeholder check,
and the full reason ENABLE_DASH_SUPPORT=n is load-bearing. Upstream's
Makefile defaults DASH on and appends -DENABLE_DASH_SUPPORT via
EXTRA_CFLAGS +=, but the SlackBuild passes EXTRA_CFLAGS on the make command
line, which overrides instead of appending; the define is lost while
r8125_dash.o is still built, and it fails against a struct with members
ifdef'd out. Dropping the flag on a version bump reintroduces the failure.

Also record that Realtek edits a listing's description in place without
re-rolling the tarball, so a changed blurb is not a release. Verified this
session: the 9.018.00 description now reads "kernel up to 7.1" while
Version, UpdateTime and MD5 are all unchanged.

The nvchecker clean-sweep paragraph was already staged in the working tree
from an earlier session and is included here.

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

1 files changed, 44 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index d53c93a..e746418 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -187,6 +187,43 @@ and `binary-i386`).
 Packages such as `SecLists`, `exploitdb` install data files rather than
 compiled binaries. No stripping needed.
 
+### Out-of-tree kernel modules — `r8125`
+
+Builds against installed kernel headers, so the package is kernel-specific:
+`PKGVER` embeds the kernel version and the name comes out as
+`r8125-<version>_<kernel>-<arch>-<build>_SBo.tgz`. `KERNEL` defaults to the
+running `uname -r`; override it to build for a kernel that is installed but
+not booted (e.g. right after a kernel upgrade, before rebooting):
+
+```bash
+KERNEL=6.1.0 ./r8125.SlackBuild          # target a specific kernel
+PRINT_PACKAGE_NAME=1 ./r8125.SlackBuild  # check output name, no root needed
+```
+
+`doinst.sh` ships an `@KERNEL@` placeholder that `sed` replaces at build
+time, so the packaged copy carries a literal kernel version and its `depmod`
+runs against the right tree. When verifying a build, confirm the placeholder
+is gone from the packaged `doinst.sh`.
+
+**DASH must stay disabled.** The make invocation passes
+`ENABLE_DASH_SUPPORT=n`, and it is load-bearing, not cosmetic. Upstream's
+Makefile defaults it to `y` and adds `-DENABLE_DASH_SUPPORT` through
+`EXTRA_CFLAGS +=`, but the SlackBuild passes `EXTRA_CFLAGS="$SLKCFLAGS"` on
+the make command line, which *overrides* the Makefile's value rather than
+appending to it. The define is lost while `r8125_dash.o` is still built, and
+`r8125_dash.c` then fails to compile against a struct whose members are
+`#ifdef`'d out. Dropping the flag on a version bump brings the failure
+straight back. The r8168 SBo package uses the same `EXTRA_CFLAGS` override
+and builds only because its Makefile happens to default DASH off. DASH is
+out-of-band management hardware, unused here.
+
+Upstream is tracked against Realtek's download API, not a git forge, so the
+`.info` `DOWNLOAD` points at a mirror of the tarball rather than Realtek
+directly (their download endpoint is an interstitial page, not a file).
+Realtek edits the listing's description text in place without re-rolling the
+tarball, so a changed blurb is not a new release: compare `Version`,
+`UpdateTime` and the MD5 before concluding anything changed.
+
 ---
 
 ## Test-building
@@ -286,6 +323,13 @@ nvchecker -c .extras/nvchecker.toml
 When a new version is detected, update `VERSION` in both `.SlackBuild` and
 `.info`, then run `sbofixinfo` to refresh checksums.
 
+**When the sweep reports every package current, record that and stop in one
+pass:** write the `LAST_SWEEP` report (date plus the shipped-vs-upstream
+table), and update `HANDOFF.md` with the sweep result and date. Both are
+local-only, gitignored artifacts. The point is that a clean sweep is a
+complete unit of work, no follow-up step is left pending, so the next session
+reads `HANDOFF.md` and moves on.
+
 **Every package added to this repo must have a corresponding entry in
 `.extras/nvchecker.toml`.**