Diff
1diff --git a/AGENTS.md b/AGENTS.md
2index 760c1091185701b65732a071cd566b35f2c2ea69..c6652543dc2ad94207a138b72f7c44e8ca5592fd 100644
3--- a/AGENTS.md
4+++ b/AGENTS.md
5@@ -1,5 +1,7 @@
6-- Don't attempt to edit the generated templ code
7-- Don't invoke ANY go commands other than `go vet` and `go mod tidy`
8+## IMPORTANT
9+
10+- Don't edit the generated templ code or mock files
11+- Don't invoke ANY go commands, the development workflow is orchestrated with make targets
12
13 ## Architecture
14
15@@ -19,3 +21,17 @@
16 **Background Jobs**: Video fetcher (5min intervals), cleanup routine (1hr intervals) - both disabled in dev mode
17
18 **Directory Structure**: `cmd/` (main), `config/`, `db/`, `models/`, `handler/`, `httpserver/`, `pages/` (templ), `lib/clients/`, `lib/downloader/`, `feedparser/`, `migrations/`, `assets/`
19+
20+## Development Workflow
21+
22+All Go tooling is managed via `make` targets. Never run `go` commands directly.
23+
24+**Make Targets**:
25+
26+- `make lint` — runs `go mod tidy`, `go vet`, and golangci-lint (lint + fmt). Use to check code quality.
27+- `make test` — runs `go test -timeout=30s -race ./...`
28+- `make templ` — generates Go code from `.templ` files via `templ generate`. Required before build.
29+- `make gen-mocks` — regenerates mock files in `mocks/` using moq. Run after changing interfaces in `db/`, `feedparser/`, or `lib/clients/youtube/`.
30+- `make migrate` — applies PostgreSQL migrations from `migrations/` dir. Configurable via `DB_URI` env var (default: `postgres://ytrssil:ytrssil@localhost:5432/ytrssil?sslmode=disable`)
31+
32+**Tool binaries** are installed into `bin/` locally (golangci-lint, moq, migrate) and auto-installed by their respective targets.