From e24a401ffbac6deaad97361eba14a82efb8eaacf Mon Sep 17 00:00:00 2001
From: l4kr <neat.rain2083@genoslab.net>
Date: Tue, 14 Jul 2026 11:17:23 +0200
Subject: [PATCH] Add AGENTS.md with release workflow instructions

Codifies the publish process this project follows so any AI agent
picks it up automatically: bump patch version every change, validate
before publishing, commit/tag/push to the Gitea remote, build the
self-contained win-x64 exe, and keep only the 3 most recent release
zips locally.
---
 AGENTS.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3ce40b5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,99 @@
+# Futonizer — Agent Instructions
+
+These instructions apply to every change made in this project by an AI
+coding agent. Follow them automatically, without being asked, whenever you
+finish a piece of work here.
+
+## 1. Always bump the version after making a change
+
+Every time you make a code change (bug fix, feature, tweak — anything that
+isn't a pure no-op), bump the patch version by exactly `0.0.1` in
+`Futonizer.csproj`:
+
+```xml
+<Version>X.Y.Z</Version>
+<FileVersion>X.Y.Z.0</FileVersion>
+```
+
+Both lines must be bumped together and stay in sync (`FileVersion` is just
+`Version` + `.0`). Check the current value with:
+
+```
+grep -n "<Version>" Futonizer.csproj
+```
+
+Do this even for small fixes — one bump per unit of work you deliver, not
+per file changed.
+
+## 2. Build and validate before publishing
+
+1. `cd Futonizer && "/mnt/c/Program Files/dotnet/dotnet.exe" build Futonizer.csproj -c Release`
+   — must show `0 Warning(s)` / `0 Error(s)`.
+2. Run the `diagnostics` tool on any file you touched — must come back clean.
+3. If you changed `Services/FileNameHelper.cs` (or similar pure-logic
+   files), validate with a disposable scratch console project instead of
+   trusting the change blindly:
+   - Create `Futonizer/_scratch_test/scratch.csproj` (minimal console app,
+     `net10.0`, with `<Compile Include="..\Services\FileNameHelper.cs" />`).
+   - Write test cases in `Program.cs` covering the new behavior **plus**
+     every previously-established regression case (accumulate these across
+     sessions — don't just test the newest scenario).
+   - Run via `"/mnt/c/Program Files/dotnet/dotnet.exe" run --project _scratch_test/scratch.csproj`.
+   - Confirm all cases pass, then **delete `_scratch_test`** before
+     committing — it must never be committed.
+
+## 3. Commit, tag, and push
+
+```
+git add -A
+GIT_EDITOR=true git commit -m "<short imperative summary>
+
+<optional body explaining the bug/feature, root cause, and fix>"
+GIT_EDITOR=true git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin main --tags
+```
+
+Remote is a Gitea instance (`sshtea.genoslab.net`), not GitHub — there is
+no `gh` CLI and no automated release upload. Publishing is git-only
+(commit + annotated tag + push).
+
+## 4. Publish a self-contained build
+
+```
+"/mnt/c/Program Files/dotnet/dotnet.exe" publish Futonizer.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -o publish
+mkdir -p "publish/Futonizer-vX.Y.Z" && cp publish/Futonizer.exe "publish/Futonizer-vX.Y.Z/Futonizer.exe"
+rm -f publish/Futonizer.exe publish/Futonizer.pdb
+powershell.exe -NoProfile -Command "Compress-Archive -Path 'publish\Futonizer-vX.Y.Z\Futonizer.exe' -DestinationPath 'Futonizer-vX.Y.Z.zip' -CompressionLevel Optimal"
+rm -rf publish/Futonizer-vX.Y.Z bin/Release/net10.0-windows/win-x64
+```
+
+Notes:
+- `dotnet` is only reachable via the full path
+  `"/mnt/c/Program Files/dotnet/dotnet.exe"` (not on `$PATH` as `dotnet`
+  in this shell).
+- There's no `zip`/`7z` in this shell — use PowerShell's
+  `Compress-Archive` via `powershell.exe -NoProfile -Command "..."`.
+- Verify the resulting zip contains only `Futonizer.exe` (~69-72MB
+  compressed) with `unzip -l Futonizer-vX.Y.Z.zip`.
+
+## 5. Only keep the last 3 release zips
+
+`*.zip` files live in the project root and are gitignored (kept locally
+only, per user preference — not committed). After publishing a new
+version, **delete any zip beyond the 3 most recent versions**:
+
+```
+ls -1v Futonizer-v*.zip
+```
+
+Sort by version (not by date/name alone — use natural/version sort as
+shown above), keep the newest 3, delete the rest, e.g.:
+
+```
+rm -f Futonizer-v<oldest>.zip
+```
+
+## 6. Report back
+
+Summarize what changed, what validation was run (and its result), and
+confirm the new version number, commit hash, tag, and zip filename.