diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d340301
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,14 @@
+# dap-tui — agent notes
+
+- Run `cargo test` after any change (parser, engine, and TestBackend UI tests live in-tree).
+- **After every code change, reinstall the binary** so `dap-tui` on PATH picks it up:
+  ```bash
+  cargo install --path . --force
+  ```
+  Verify the install with:
+  ```bash
+  sha256sum ~/.cargo/bin/dap-tui target/release/dap-tui   # hashes must match
+  ```
+- Commit and push changes to the Gitea remote (`origin`) when done.
+
+See `../AGENTS.md` for the global rules (sudo/pkexec, Gitea push, etc.).
diff --git a/README.md b/README.md
index 9792406..6c37193 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,10 @@ cargo build --release
 ./target/release/dap-tui            # uses ~/.config/dap-sync/config.toml
 ./target/release/dap-tui --config /path/to/config.toml
 ./target/release/dap-tui --skip-mirror   # skip the StorageBox → local mirror step
+
+# install/update the `dap-tui` command (~/.cargo/bin) with the new build
+cargo install --path . --force
+dap-tui
 ```
 
 ## Keybindings