1 files changed, 50 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..282bcd6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,50 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this is
+
+`sb-builder`: a PyQt6 desktop GUI that drives the SlackBuild tooling on a
+Slackware -current build VM (slackrepo, mkhint, sbpull, sbshadow) over ssh.
+Two programs: the GUI (`sb_builder/`, PyQt6 incl. QtDBus, stdlib otherwise)
+and `remote/sbb-remote`, a single-file stdlib-only Python helper deployed on
+the VM. Do not add third-party dependencies to either.
+
+Design and phasing: `docs/superpowers/specs/`. Phase 1 (core) is
+`2026-10-19-sb-builder-phase1-design.md`.
+
+## How it works
+
+- Every GUI action is `ssh <target> sbb-remote <cmd> [args]`; the helper
+  answers with JSON. `sb_builder/remote.py` is the only code that runs ssh
+  (and local `virsh`).
+- Trust boundary: the helper runs only a fixed table of job kinds and builds
+  argv itself from validated args. Never pass shell strings or paths from the
+  GUI to the helper.
+- Jobs run detached on the VM (`setsid`, `stdin=/dev/null`), one at a time
+  under a flock, logging to `<state_dir>/jobs/<id>/`. The GUI can disconnect
+  and reattach with `job-follow <id> <offset>`.
+- Jobs never get input. Any tool run as a job must be non-interactive
+  (`--yes`/`--no` style flags). If a tool needs a flag it lacks, add it in
+  that tool's own repo (e.g. `slackrepo_setup` for sbshadow, `mkhintfile`
+  for mkhint) rather than working around it here.
+
+## Conventions
+
+- GUI config: `$XDG_CONFIG_HOME/sb-builder/config.toml`. Helper config:
+  `/etc/sb-builder/config.toml` on the VM. Both read with `tomllib`, both
+  have shipped `config.example.toml` files, defaults live in code.
+- One file per GUI tab.
+- Deploying to the VM is outward-facing: confirm before `install.sh --remote`.
+- Placeholders only in code, docs, tests and commits.
+
+## Testing
+
+No test suite yet. Planned (phase 1 spec): `python3 -m unittest discover
+tests`, with the GUI smoke test under `QT_QPA_PLATFORM=offscreen`.
+
+## Repo facts
+
+- License: GPLv2 only (`LICENSE`, header in each source file).
+- Work directly on master.
+- `.superpowers/` is brainstorming scratch, ignored.