1 files changed, 86 insertions, 0 deletions
diff --git a/docs/apkg_helpers.md b/docs/apkg_helpers.md
new file mode 100644
index 00000000..bbc54648
--- /dev/null
+++ b/docs/apkg_helpers.md
@@ -0,0 +1,86 @@
+# apkg helper scripts
+
+autils includes several helper scripts that work alongside `apkg` for package inspection, cleanup, and maintenance. See `man <program>` for full details on each command.
+
+## apkg-chroot
+
+Enter a chroot environment with virtual filesystems mounted. Useful for building packages or performing system maintenance inside an alternative root.
+
+```sh
+apkg-chroot /mnt/alice                  # launch interactive shell
+apkg-chroot /mnt/alice apkg -i mypkg    # run a command inside the chroot
+```
+
+Must be run as root. Mounts `/dev`, `/proc`, `/sys`, `/run`, copies `/etc/resolv.conf`, and cleans up all mounts on exit.
+
+## apkg-clean
+
+List stale `.spm` package files and orphaned source tarballs that are no longer referenced by any current package recipe. Pipe to `xargs rm` to actually clean up.
+
+```sh
+apkg-clean             # list all unreferenced files
+apkg-clean -p          # list only stale packages
+apkg-clean -s          # list only stale sources
+apkg-clean | xargs rm  # remove them
+```
+
+## apkg-deps
+
+Show runtime library dependencies of an installed package. Uses `ldd` to find shared libraries needed by the package's binaries, then maps those libraries back to the packages that provide them.
+
+```sh
+apkg-deps mypkg
+```
+
+Useful for discovering implicit runtime dependencies not listed in the formal `depends` file. Excludes the package itself and base system packages (gcc, musl, binutils, glibc).
+
+## apkg-foreign
+
+List installed packages that are not found in any configured repository. These may have been installed from an external source or had their recipes removed.
+
+```sh
+apkg-foreign
+```
+
+Takes no arguments; outputs one package name per line.
+
+## apkg-genabuild
+
+Scaffold a new package recipe from a source URL. Parses the name and version from the URL and creates a directory with skeleton `abuild` and `info` files.
+
+```sh
+apkg-genabuild https://example.com/mypkg-1.2.3.tar.gz
+apkg-genabuild https://github.com/user/repo/archive/v1.0.tar.gz myname
+```
+
+Special handling for GitHub tag archives, PyPI packages (prefixes `python-`), and CPAN packages (prefixes `perl-`). An optional second argument overrides the derived package name.
+
+## apkg-orphan
+
+List orphan packages: packages that are installed and exist in a repository, but have no other installed package depending on them. These may be safe to remove.
+
+```sh
+apkg-orphan
+```
+
+Takes no arguments; outputs one package name per line.
+
+## apkg-purge
+
+Remove a package and all its dependencies that are no longer needed by any other installed package. This is a "deep" removal compared to `apkg -r` which only removes the specified package.
+
+```sh
+apkg-purge mypkg       # dry-run: show what would be removed
+apkg-purge -p mypkg    # actually purge from the system
+```
+
+## apkg-redundantdeps
+
+Find redundant entries in `depends` files. A dependency is redundant if another listed dependency already pulls it in transitively.
+
+```sh
+apkg-redundantdeps mypkg       # check one package
+apkg-redundantdeps              # check all packages
+apkg-redundantdeps -f mypkg     # fix by removing redundant entries
+apkg-redundantdeps -f           # fix all packages
+```