From 1dbb77e238b5ed3ce30da32a1fa968f89f72bbda Mon Sep 17 00:00:00 2001
From: iceman1001 <iceman@iuse.se>
Date: Mon, 14 Sep 2026 16:57:59 +0200
Subject: [PATCH] lesson learned

---
 AGENTS.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 2e10ef9a2..6b4b4e166 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -52,6 +52,34 @@ test):
    `tools/pm3_tests.sh` coverage if you're adding a new command/module that
    can be exercised offline.
 
+### Never `rm -rf` an `obj/` directory
+
+The ARM-side build has no `mkdir` for its object directories — only the host
+build creates its own. `armsrc/obj/`, `armsrc/obj/Standalone/` and
+`bootrom/obj/` exist because each is held open in git by a tracked `.dummy`
+file, and `make clean` deliberately deletes only the files *inside* them:
+
+```
+clean:
+	$(Q)$(RM) $(OBJDIR)$(PATHSEP)*.o
+	...
+```
+
+Delete such a directory and nothing recreates it. Every subsequent build dies
+with messages that give no hint a tracked file went missing:
+
+```
+Error. Cannot open output file obj/fpga_all.bit.z
+Fatal error: can't create obj/start.o: No such file or directory
+```
+
+`git checkout -- armsrc/obj/.dummy armsrc/obj/Standalone/.dummy bootrom/obj/.dummy`
+puts it back. `git status` showing a deleted `.dummy` is the tell.
+
+If you script a build matrix, switch `PLATFORM=` / `STANDALONE=` and let make
+decide what to rebuild — changing those changes the defines, which is enough to
+force the recompile you want.
+
 ## Code style
 
 - Respect the style used in this project: trailing
@@ -134,3 +162,5 @@ Don't omit this to make a PR look purely human-written.
 - Don't introduce a dependency in one client build file without mirroring it
   in the other two.
 - Don't submit ARM-side changes only test-built for one platform target.
+- Don't `rm -rf` any `obj/` directory to force a rebuild — it deletes tracked
+  `.dummy` files and breaks the build until they are restored. Use `make clean`.