1 files changed, 33 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5024c4d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,33 @@
+# AGENTS.md
+
+`dist-upgrade` is a single bash script that updates a Slackware `-current`
+system with `slackpkg` and verifies the initrd afterwards.
+
+## Testing
+
+Run all of these before calling a change done:
+
+    bash -n dist-upgrade
+    ./dist-upgrade --self-test
+    shellcheck --exclude=SC2218 dist-upgrade
+
+SC2218 is a shellcheck 0.11.0 false positive: it flags a function called on the
+left of a pipe inside another function definition (`b() { a | cat; }`), even
+when `a` is defined above. Keep it excluded; do not restructure the pipeline to
+silence it.
+
+## Do not
+
+- Do not run the script itself, or any `slackpkg` command, in this repo. It
+  performs a real system upgrade and only makes sense on the user's Slackware
+  box as root.
+- Do not add config, cache or log files. The script is self-contained and
+  configured through the `INITRD` environment variable.
+
+## Conventions
+
+- One file, no unrequested abstractions. Standard library and Slackware's own
+  tools over new dependencies.
+- Anything that parses initrd contents or `mkinitrd` output gets a case in
+  `--self-test`.
+- License is GPLv2-only. New source files carry the copyright header.