From 2b949c4f00cc45cbe75fdcb8837d08397a23e674 Mon Sep 17 00:00:00 2001
From: Henrik Muehe <henrik.muehe@gmail.com>
Date: Sun, 3 May 2026 15:10:25 +0200
Subject: [PATCH] docs: AGENTS.md - branch model and where-does-it-go guide

---
 AGENTS.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e28ea1f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,77 @@
+# Onefinity firmware — agent guidelines
+
+## Branch model
+
+This fork lives on **two long-lived branches**:
+
+- **`master`** — public-facing fork. General-use upgrades on top of
+  upstream OneFinity firmware: V09 UX redesign, Font Awesome 6, faster
+  cold boot, macOS dev/deploy tooling, build & flash docs, SD-card
+  backup, `/api/diag/timing`, kiosk/tablet polish, and assorted
+  bug-fixes. **No A-axis, ATC, hooks, or auxcnc/ESP content.** Aim for
+  changes that benefit any Onefinity owner.
+
+- **`esp-a-axis`** — bespoke shop branch. Stacks on top of `master`
+  and adds everything specific to the auxcnc-ESP-driven A axis and
+  the ATC: `Hooks` (ATC IPC), `AuxAxis` (ESP serial driver),
+  `ExternalAxis` (virtual A through gplan), `AuxPreprocessor` (M100-M103),
+  Z-A coupling interlock, the A-axis UI surface, and the
+  `/api/aux/*` endpoints.
+
+Upstream:
+- `upstream` → `https://github.com/OneFinityCNC/onefinity-firmware.git`
+- `origin`   → Gitea (`https://gitea.home.muehe.org/muehe/onefinity-firmware.git`)
+
+`origin/pre-split-backup` is a tag preserving the pre-split master
+tip. Keep it indefinitely until further notice.
+
+## Where does a change go?
+
+| Change | Branch |
+|---|---|
+| UI polish, theme, layout that any user benefits from | `master` |
+| Build / install / boot performance | `master` |
+| Diagnostics, logging, generic Python / Tornado fixes | `master` |
+| Anything that touches `AuxAxis`, `ExternalAxis`, `Hooks`, `AuxPreprocessor` | `esp-a-axis` |
+| Anything mentioning the auxcnc ESP, `/dev/ttyUSB0`, the M100-M103 ATC pneumatics, or motor index 4 | `esp-a-axis` |
+| Z-A coupling interlock, ATC tool change sequencing | `esp-a-axis` |
+| A-axis UI (DRO row, jog tile, settings page, A-axis routes) | `esp-a-axis` |
+| W → A renames or aux.json migrations | `esp-a-axis` |
+
+When in doubt: ask "would this be useful on a stock Onefinity with no
+ESP attached?" If yes → `master`. If no → `esp-a-axis`.
+
+## Workflow
+
+```bash
+# Day-to-day shop / hardware work (default)
+git checkout esp-a-axis
+# … do work, commit …
+git push origin esp-a-axis
+
+# Generic improvement to master
+git checkout master
+# … do work, commit …
+git push origin master
+
+# After landing on master, replay esp-a-axis on top
+git checkout esp-a-axis
+git rebase master
+git push --force-with-lease origin esp-a-axis
+```
+
+If a change accidentally lands on `master` but is bespoke (touches
+the file table above), move it: `git reset --hard <prev>` on master,
+cherry-pick onto `esp-a-axis`, force-push master.
+
+## Deploy
+
+- `./deploy.sh local` — UI bundle on `localhost:8770` (tmux session
+  `onefin-local`). No controller backend; A-axis row stays hidden.
+- `./deploy.sh hardware` — rsync to the Pi over SSH, restart
+  `bbctrl.service`. Use the `esp-a-axis` branch on the shop Pi.
+- `./deploy.sh prod` — bundle a release tarball.
+
+See `.pi/BUILD.md` for the full build / flash / cross-compile flow.
+
+## Commit before ending a turn; push after significant changes.