From 9c4b73849795da5d6870dadc861d94e44fb6bae5 Mon Sep 17 00:00:00 2001
From: Emil Kosz <ekosz@int.pl>
Date: Sat, 5 Sep 2026 17:13:42 +0200
Subject: [PATCH] docs: add AGENTS.md

So vibecoding agents can understand the project.
---
 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..0dc7b82
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,77 @@
+# AGENTS.md — builders_rubenslte
+
+What this repo is: the build driver + documentation for producing a **TWRP
+recovery** (`recovery.img`) for the Samsung Galaxy Tab Active SM-T365
+(codename `rubenslte`, Qualcomm MSM8926, Android 5.1.1 / omni `twrp-5.1`).
+
+Three repos cooperate:
+
+| Repo | Role |
+|------|------|
+| `builders_rubenslte` (this) | `build_twrp.sh` (driver), `shell.nix` (env), `patches/`, docs |
+| `rubenslte/twrp_device_samsung_rubenslte` | device tree (`BoardConfig.mk`, `mkbootimg.mk`, `dtbtool`) |
+| `rubenslte/android_kernel_samsung_rubenslte` | Samsung msm8226 stock kernel, built from source |
+
+This drive builds from **source**: kernel, dt.img and ramdisk are all produced,
+never prebuilt. The artifact is `recovery.img` (currently 10,407,952 bytes,
+TWRP 3.7.0_9-0) and has passed on-device tests on real hardware.
+
+## Commands
+
+```bash
+./build_twrp.sh                # full build -> recovery.img at repo root
+./build_twrp.sh --no-sync      # iteration: skip repo sync / tree refresh / patches
+./build_twrp.sh clean          # remove twrp-build/ and recovery.img
+./build_twrp.sh env            # interactive shell inside the nix-shell FHS env
+```
+
+Verification without nix (cheap): `bash -n build_twrp.sh`.
+
+## How to work here
+
+- The build only runs inside the nix-shell FHS environment (`shell.nix`).
+  `build_twrp.sh` re-enters it via a stdin pipe; **do not rely on
+  `nix-shell --run`** (the `exec android-env` shellHook swallows it) and do not
+  run two nix-shells at once (nix store lock deadlock).
+- A full build is slow (first run downloads ~2-3 GB via `repo sync`; kernel +
+  recovery compile takes a while). For source edits, iterate with
+  `./build_twrp.sh --no-sync` against the existing `twrp-build/` tree.
+- Prefer editing the *device tree repo* (BoardConfig.mk / mkbootimg.mk) over
+  patching the omni tree post-sync. Only use `patches/` for fixes to the
+  upstream 5.1 sources that cannot live in the device tree.
+- Commit style in this repo: short lowercase-imperative subject, no body
+  (`Refactor build_twrp.sh and document the recovery build`). Stage with
+  `git add -A`; `recovery.img` and `recovery-stock.img` are intentionally
+  untracked (gitignored).
+
+## Invariants — do not "simplify" these
+
+- **`BoardConfig.mk`**: `INSTALLED_DTIMAGE_TARGET` and `BOARD_MKBOOTIMG_ARGS`
+  must stay *recursive* (`=`, never `:=`). They are expanded after
+  `PRODUCT_OUT`/`KERNEL_OUT` exist; see the `mkbootimg.mk` header comment for
+  the include-order reasoning.
+- **`mkbootimg.mk`**: the dt.img rule depends on `INSTALLED_KERNEL_TARGET`
+  (not `TARGET_PREBUILT_INT_KERNEL`), and the recovery-ramdisk override
+  (drop tzdata, keep only en/pl languages, **LZMA** compression) is what keeps
+  the image under the 10,485,248-byte partition. Changing compression or adding
+  `twres/`/`system/` files can overflow it — always re-check image size.
+- **F2FS is off.** The kernel has no F2FS driver. Never re-add
+  `TARGET_USERIMAGES_USE_F2FS`.
+- **dt.img is EUR-only** (`CONFIG_MACH_RUBENSLTE_OPEN`). Other hardware
+  variants (T365Y/AUS, T365M/KOR) need their `CONFIG_MACH_RUBENSLTE_*`
+  enabled + rebuild.
+- **SEANDROIDENFORCE** trailer and `--dt` are required on boot/recovery images
+  for Samsung bootloaders; the stock core rules don't add them.
+
+## Troubleshooting the image
+
+- `adb shell` fails with `CANNOT LINK EXECUTABLE DEPENDENCIES: library
+  "libc.so" not found` — normal: `/system` is not mounted in recovery; the ramdisk
+  has no Android root. Mount System in TWRP, or use the in-TWRP terminal.
+- `make: ... [/dt.img] Błąd 255` — the lazy-variable/`INSTALLED_KERNEL_TARGET`
+  dependency is broken; restore it per the invariants above.
+- Multi-variant boot failures — dt.img lacks the device's DTB; rebuild with the
+  right `CONFIG_MACH_RUBENSLTE_*`.
+
+For the full background: `README.md` (this repo), `patches/README.md`, and
+`twrp_device_samsung_rubenslte/README.md`.
\ No newline at end of file