AGENTS.md: align with CLAUDE.md and document full agent workflowmain

1 files changed, 109 insertions, 1 deletions

diff --git a/AGENTS.md b/AGENTS.md
index c2b95bd..059e520 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,12 +43,24 @@ Each package lives in its own top-level subfolder:
 
 ---
 
+## Packages Maintained Elsewhere
+
+Several packages that used to live in this repo are now danix-official on
+SlackBuilds.org and maintained in the separate
+[sbo-slackbuilds](https://github.com/danixland/sbo-slackbuilds) repo:
+`ffuf`, `gobuster`, `nuclei`, `feroxbuster`, `metasploit-framework-bin`,
+`SecLists`, and `exploitdb`. Do not modify those packages here; changes
+to them belong in `sbo-slackbuilds`.
+
+---
+
 ## Package Build Strategies
 
 Before updating or adding a package, identify which build strategy it uses:
 
 | Strategy | Examples | Key indicator |
 |----------|----------|---------------|
+| Python source | netexec | `python3 -m build`, `python3.SlackBuild` |
 | Go source | ffuf, gobuster, nuclei | `go build`, `REQUIRES="google-go-lang"` |
 | Autotools/cmake source | hydra, cadaver | `./configure` or `cmake` |
 | Binary repack (.deb) | metasploit-framework-bin | `ar p … data.tar.gz \| tar xzv` |
@@ -150,9 +162,79 @@ Then proceed:
 
 ---
 
+## Version Sweep
+
+The `.extras/nvchecker.toml` file tracks upstream versions for all packages
+in the suite (both in-repo and sbo-slackbuilds). A sweep compares upstream
+against what this repo carries and identifies packages that need updating.
+
+### Procedure
+
+1. Generate a throwaway nvchecker config in the scratchpad (`/tmp/opencode/`)
+   that prepends a `[__config__]` section pointing at the personal keyfile
+   (`~/.config/nvchecker/keys.toml`, provides a GitHub token for 5000 req/h)
+   plus scratchpad `oldver`/`newver` paths, then appends the stanzas from
+   `.extras/nvchecker.toml`.
+
+2. Run `nvchecker -c <throwaway-config>` on the throwaway config. With a
+   fresh `oldver`, every stanza reports "updated to X" — that is the
+   *upstream* version, not a diff.
+
+3. For each **in-repo** package (cadaver, netexec, windows-binaries,
+   webshells), compare the reported upstream version against the `VERSION=`
+   in that package's `.info` file. Packages maintained in `sbo-slackbuilds`
+   are out of scope for this repo's sweep.
+
+4. Update `LAST_SWEEP` (gitignored) with the date and a table showing
+   carried version, upstream version, and status (current / needs bump)
+   for each in-repo package.
+
+5. For any package that needs a bump, follow the Mandatory Workflow:
+   Updating a Package Version above.
+
+### Important notes
+
+- Never run `nvchecker -c .extras/nvchecker.toml` directly — the tracked
+  config has no `[__config__]`, so GitHub stanzas hit the anonymous rate
+  limit (60 req/h) and 403.
+- Probe a single package with `nvchecker -c <config> -e <name>` when
+  testing a specific stanza.
+- Never audit GitHub repos with raw `curl` loops — a burst burns the
+  anonymous quota and later calls 403.
+
+---
+
 ## SlackBuild Scripting Rules
 
-- Base all scripts on the SBo template: https://slackbuilds.org/templates/
+### Templates (source of truth)
+
+Local templates live in `~/Templates/SlackBuilds/`. Always start from the
+matching template there rather than writing a SlackBuild or its accompanying
+files from scratch. The directory holds per-build-type SlackBuild templates
+(`autotools-template.SlackBuild`, `cmake-template.SlackBuild`,
+`go-template.SlackBuild`, `python-template.SlackBuild`, etc.) and shared
+support files (`slack-desc`, `template.info`, `doinst.sh`, `README`).
+
+When the local template and the upstream SBo template disagree, the local one
+wins. Only fall back to the [SBo template](https://slackbuilds.org/templates/)
+if no local template fits.
+
+The `sbo/` and `conraid/` subdirectories are git clones kept up to date by
+`~/Templates/SlackBuilds/update-templates.sh`. Run that script (or let the
+desktop autostart handle it) before starting work on a new package to ensure
+templates reflect the latest upstream conventions.
+
+### Copyright line
+
+In every `.SlackBuild`, the maintainer copyright line is exactly:
+
+```
+# Copyright <year> danix <danix@danix.xyz>
+```
+
+### General rules
+
+- Base all scripts on the local templates above; fall back to the SBo template: https://slackbuilds.org/templates/
 - Use `set -e` (abort on error).
 - Honor `$TMP`, `$BUILD`, `$TAG`, `$OUTPUT`; provide defaults if unset.
 - Detect `$ARCH` and set `SLKCFLAGS` and `LIBDIRSUFFIX` accordingly.
@@ -269,6 +351,32 @@ Commit conventions:
 
 ---
 
+## Git Hooks
+
+Versioned source lives in `.extras/hooks/`. After a fresh clone, install them:
+
+```bash
+cp .extras/hooks/* .git/hooks/ && chmod 0755 .git/hooks/{pre,post}-commit
+```
+
+- `pre-commit` — runs `sbolint` on each changed package; aborts the commit on
+  any error. Also auto-removes staged source-archive symlinks and blocks
+  staged regular source archives (`*.tar.*`, `*.zip`, `*.deb`, etc.). Skip
+  with `SBOLINT=no git commit ...`.
+- `post-commit` — for each added/updated `*.SlackBuild`, offers to build the
+  SBo submission tarball into `SBo/<package>.tar.gz`.
+
+### `SBO_ARCHIVE` (non-interactive archive answer)
+
+`post-commit` normally prompts on a TTY. To answer without one (agents,
+scripts), set `SBO_ARCHIVE`:
+
+- `SBO_ARCHIVE=yes git commit ...` — build the tarball, no prompt
+- `SBO_ARCHIVE=no  git commit ...` — skip, no prompt
+- unset + TTY → interactive prompt; unset + no TTY → skip
+
+---
+
 ## What Requires User Confirmation
 
 Stop and ask before doing any of the following: