From ad3e879c4244def8bcf6b59f183b09df517f865f Mon Sep 17 00:00:00 2001
From: Daniel Arroyo <darroylat@gmail.com>
Date: Wed, 8 Jul 2026 19:26:16 -0400
Subject: [PATCH] Document build artifacts in AGENTS.md

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

diff --git a/AGENTS.md b/AGENTS.md
index 6232d97..75640d1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,6 +24,22 @@ go test ./...
 ./scripts/deploy.sh
 ```
 
+## Build Artifacts
+
+The following are **not tracked** in git — they are regenerated by `make clean && make build-all`:
+
+| Path | Description |
+|---|---|
+| `bin/` | Linux AMD64 + ARM64 built binaries |
+| `server` | Local macOS dev binary (`go build ./cmd/server`) |
+| `.data/` | Runtime data dir created by `make clean` |
+| `dist/` | Root-level build output |
+| `web/dist/` | Frontend build output |
+| `internal/webui/dist/` | Embedded frontend in Go |
+| `*.deb` | Debian packages built by `make package` |
+
+The deploy pipeline always rebuilds from source + embedded frontend. Tracking prebuilt binaries bloats history with opaque diffs and produces unresolvable merge conflicts.
+
 ## Version Bumping
 
 Before each push that contains user-facing changes, run the version bump script: