Initial commit: Slackware -current upgrade helper with initrd verification

1 files changed, 68 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..44c54bd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# dist-upgrade
+
+Update a Slackware `-current` system with `slackpkg`, then verify the initrd
+still matches the newly installed kernel and still contains the modules the
+system needs to boot.
+
+The script wraps the standard `-current` routine (`update`, `install-new`,
+`upgrade-all`, `clean-system`, `new-config`) and adds three initrd checks so a
+stale or incomplete initrd cannot silently leave you with an unbootable system.
+
+## Usage
+
+    sudo ./dist-upgrade          # unattended
+    sudo ./dist-upgrade -i       # interactive, slackpkg prompts normally
+
+Options:
+
+- `-i`, `--interactive` run slackpkg with its normal prompts
+- `-h`, `--help` print usage
+- `--self-test` run the internal logic checks and exit (no root needed)
+
+Environment:
+
+- `INITRD` initrd to inspect (default `/boot/initrd-generic.img`)
+
+## What it does
+
+1. Snapshots the current initrd's kernel version and module list.
+2. Runs `slackpkg update`, `install-new`, `upgrade-all`, `clean-system`,
+   `new-config`.
+3. Checks:
+   - the initrd's kernel version against the newest installed kernel,
+   - the modules `mkinitrd_command_generator.sh` says are needed against the
+     initrd's contents,
+   - the module set against the pre-upgrade snapshot (notices modules lost).
+4. Reports whether a reboot is recommended.
+
+Unattended mode runs the package commands with `-batch=on -default_answer=y`.
+`clean-system` is the exception: unattended it only lists packages that are not
+part of the official Slackware set and removes nothing, so third-party or
+local packages are never deleted silently. Use `-i` to review and remove.
+
+## Requirements
+
+Slackware `-current`, run as root. Needs `slackpkg`, `cpio` and `gzip`; `zstd`
+and `xz` are used only if the initrd is compressed with them. The module
+bootability check uses Slackware's own
+`/usr/share/mkinitrd/mkinitrd_command_generator.sh` when present.
+
+## Testing
+
+    bash -n dist-upgrade
+    ./dist-upgrade --self-test
+
+`--self-test` builds a small gzip/cpio initrd in a temp dir and round-trips it
+through the reader, alongside checks of the module/version parsers.
+
+## License
+
+GPLv2 (version 2 only). See [LICENSE](LICENSE).
+
+## 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.