docs updated

1 files changed, 245 insertions, 0 deletions

diff --git a/docs/05-using_apkg.md b/docs/05-using_apkg.md
new file mode 100644
index 00000000..bbf2ce69
--- /dev/null
+++ b/docs/05-using_apkg.md
@@ -0,0 +1,245 @@
+# Using autils
+
+autils is a collection of POSIX shell scripts for source-based package management on Alice Linux.
+
+For full command details, see the man pages: `man apkg`, `man reposync`, etc.
+
+## Installation
+
+```sh
+make install
+```
+
+This installs all scripts to `/usr/bin` and man pages to `/usr/share/man/man8`. Override with:
+
+```sh
+make install DESTDIR=/tmp/root PREFIX=/usr/local
+```
+
+## Core concepts
+
+The package manager, **apkg**, builds packages from source using `abuild` recipe files and installs them as `.spm` packages via the **spm**(8) backend. Package recipes live in git repositories referenced by the `APKG_REPO` environment variable.
+
+Configuration is done through environment variables: there is no config file.
+
+## Basic usage
+
+### Building a package
+
+From inside a recipe directory:
+
+```sh
+cd /path/to/repo/mypkg
+apkg
+```
+
+This fetches sources, verifies checksums, builds, and creates a `.spm` in `$APKG_PACKAGE_DIR`.
+
+### Installing and upgrading
+
+```sh
+apkg -i mypkg          # build and install
+apkg -i                # same, from inside the recipe directory
+apkg -I firefox        # install with automatic dependency resolution
+apkg -u mypkg          # upgrade (rebuild and reinstall)
+apkg -f mypkg          # force rebuild even if .spm already exists
+apkg -o mypkg          # download sources only, don't build
+```
+
+### Removing packages
+
+```sh
+apkg -r mypkg          # remove a package
+apkg-purge mypkg       # show what would be removed (dry-run)
+apkg-purge -p mypkg    # remove package and its unneeded dependencies
+```
+
+### Searching and listing
+
+```sh
+apkg -s icon           # search packages by name pattern
+apkg -s -v icon        # search with version info
+apkg -a                # list all installed packages
+apkg -a -v             # list installed packages with versions
+apkg -S libpng.so      # find which package owns a file
+apkg -l                # list outdated packages on the system
+```
+
+### Dependency queries
+
+```sh
+apkg -d mypkg          # list direct dependencies of a package
+apkg -D mypkg          # list all dependencies recursively, in install order
+apkg -j mypkg          # list packages that depend on mypkg
+```
+
+### System upgrade
+
+```sh
+apkg -U
+```
+
+This checks all installed packages for outdated versions, resolves the full dependency tree, installs any new packages, then upgrades existing ones. Set `APKG_NOPROMPT=1` to skip the confirmation prompt (useful for scripting). Packages listed in `APKG_MASK` are skipped.
+
+### Checksums and file lists
+
+```sh
+apkg -g mypkg          # regenerate .shasum file
+apkg -k mypkg          # regenerate .files list from the .spm
+```
+
+### Triggers
+
+After installing or upgrading packages, apkg can refresh system caches:
+
+```sh
+apkg -t                # run triggers for all installed packages
+apkg -t mypkg          # run only triggers relevant to mypkg
+```
+
+Triggers include: fontconfig cache, GDK-Pixbuf loaders, GIO modules, GSettings schemas, GTK input method modules, icon theme cache, udev hardware database, X font indices, desktop MIME cache, and shared MIME database. Each trigger only fires if the package actually provides files that need it.
+
+## Helper scripts
+
+### Package inspection
+
+```sh
+apkg-deps mypkg        # show runtime library dependencies (via ldd)
+apkg-foreign           # list installed packages not found in any repo
+apkg-orphan            # list packages with no dependents installed
+```
+
+### Cleanup
+
+```sh
+apkg-clean             # list stale .spm and source files
+apkg-clean | xargs rm  # actually remove them
+apkg-clean -p          # list only stale packages
+apkg-clean -s          # list only stale sources
+```
+
+### Dependency maintenance
+
+```sh
+apkg-redundantdeps mypkg       # find transitive deps listed explicitly
+apkg-redundantdeps              # check all packages
+apkg-redundantdeps -f mypkg     # fix by removing redundant entries
+```
+
+### Scaffolding
+
+```sh
+apkg-genabuild https://example.com/pkg-1.2.3.tar.gz
+apkg-genabuild https://github.com/user/repo/archive/v1.0.tar.gz
+```
+
+Derives `name` and `version` from the URL and creates a directory with a skeleton `abuild`. Recognizes GitHub tag archives, PyPI packages (prefixes `python-`), and CPAN packages (prefixes `perl-`). An optional second argument overrides the name.
+
+## Standalone utilities
+
+### revdep: find broken library links
+
+Scans system binaries and libraries for missing shared library dependencies. Run after major upgrades, especially those with library version bumps.
+
+```sh
+revdep         # plain output
+revdep -v      # verbose progress
+```
+
+**Note:** revdep only reports problems; it does not rebuild anything. Use `apkg -f` to rebuild affected packages.
+
+### updateconf: merge .new config files
+
+When packages are upgraded, new default config files are installed with a `.new` suffix to avoid overwriting local changes. Run `updateconf` as root to interactively handle them:
+
+```sh
+updateconf
+```
+
+For each `.new` file it shows a diff and prompts:
+- **U**: update: replace current with new
+- **D**: discard: delete the `.new` file, keep current
+- **E**: edit: open current file in `$EDITOR` (default: `vi`)
+- **K**: keep: leave both files as-is
+
+### reposync: sync git repositories
+
+Syncs git-based package repos using `REPOSYNC_*` environment variables:
+
+```sh
+export REPOSYNC_CORE="https://codeberg.org/emmett1/alicelinux.git|main|/var/lib/alicelinux"
+export REPOSYNC_EXTRA="https://codeberg.org/emmett1/extra.git|main|/var/lib/alicelinux/extra"
+reposync
+```
+
+Options:
+- **`-n`**: dry-run
+- **`-l`**: log to `/var/log/reposync.log`
+- **`-f`**: force fresh clones
+- **`-h`**: help
+
+## Working in a chroot
+
+```sh
+apkg-chroot /mnt/alice                  # enter interactive shell
+apkg-chroot /mnt/alice apkg -i mypkg    # run apkg inside chroot
+```
+
+Mounts `/dev`, `/proc`, `/sys`, `/run`, copies `/etc/resolv.conf`, and cleans up on exit. Must be run as root.
+
+## Environment variables
+
+### Core paths
+
+- **`APKG_REPO`** (default: `$PWD`): Space-separated repo directories, searched in order
+- **`APKG_PACKAGE_DIR`** (default: `$PWD`): Where built `.spm` files are stored
+- **`APKG_SOURCE_DIR`** (default: `$PWD`): Source tarball cache
+- **`APKG_WORK_DIR`** (default: `$PWD`): Build working tree (extraction + fakeroot)
+- **`APKG_ROOT`** (default: `/`): Alternative install root
+
+### Build behavior
+
+- **`APKG_NOPROMPT`**: Skip confirmation prompt in `-I` and `-U`
+- **`APKG_KEEP_WORKDIR`**: Keep build tree on failure (for debugging)
+- **`APKG_ALIAS`**: Dependency substitution: `real:alias` pairs (e.g. `openssl:libressl`)
+- **`APKG_MASK`**: Packages to skip during `-l` and `-U`
+
+### Logging
+
+- **`APKG_LOG`**: Enable build logging
+- **`APKG_LOG_DIR`**: Directory for log files (filename: `$name.log`)
+
+### Compiler
+
+- **`CFLAGS`**, **`CXXFLAGS`**: Compiler flags (used by cmake builds)
+- **`CROSS_COMPILE`**: Prefix for `strip` (e.g. `x86_64-linux-musl-`)
+
+## Common workflows
+
+### Building and installing a new package
+
+```sh
+cd $APKG_REPO
+apkg-genabuild https://example.com/mypkg-1.0.tar.gz
+cd mypkg
+# edit abuild as needed, add depends file
+apkg -I mypkg
+```
+
+### Full system maintenance
+
+```sh
+reposync                     # sync repos
+apkg -U                      # system upgrade
+revdep                       # check for broken libraries
+updateconf                   # merge config files
+apkg-clean | xargs rm        # clean up stale files
+apkg-orphan                  # review packages to potentially remove
+```
+
+### Debugging a failed build
+
+```sh
+APKG_KEEP_WORKDIR=1 apkg -f mypkg
+# inspect $APKG_WORK_DIR/apkg-src-mypkg and apkg-pkg-mypkg
+```