1 files changed, 42 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d196e48
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,42 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this is
+
+`upscale-qt`: single-file PyQt6 desktop app (`upscale-qt`, no `.py`
+extension) to upscale an image with an ESRGAN model through `sd-cli`
+(stable-diffusion.cpp), compare before/after with a slider wipe, then save
+as a new file or overwrite the original. A small vision model (imajev, run
+one-shot through `llama-mtmd-cli`) suggests which upscaler to use. The only
+Python dependency is PyQt6; everything else is stdlib plus the two external
+binaries. Keep it a single file and do not add dependencies.
+
+Design spec: `docs/superpowers/specs/2026-10-30-upscale-qt-design.md`.
+
+## External tools
+
+- Upscale: `sd-cli -M upscale --upscale-model <model> -i <in> -o <out.png>`.
+  Models are `.pth`/`.safetensors`/`.gguf` files in the upscalers dir.
+- Suggestion: `llama-mtmd-cli -m <imajev gguf> --mmproj <mmproj gguf>
+  --image <in> -p <prompt>`. Its answer is free text and gets matched to a
+  filename from the upscalers dir; never trust it as a path.
+- Both run through `QProcess` so the UI never blocks.
+
+## Conventions
+
+- Images are held in a list of jobs internally even though the UI shows one
+  at a time, so batch mode can be added without a rewrite.
+- Non-GUI logic lives in module-level functions so it can be tested without
+  a display.
+- Overwrite always asks for confirmation and keeps the original's format.
+- Placeholders only in code, docs, tests and commits.
+
+## Testing
+
+No test suite yet.
+
+## Repo facts
+
+- License: GPLv2 only (`LICENSE`, header in each source file).
+- Work directly on master.