diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8aa2cbd
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,101 @@
+# AGENTS.md
+
+This file provides guidance for agents operating in the videnc-vibe repository.
+
+## Project Overview
+
+Go-based CLI tool for transcoding DVD/Blu-ray to SVT-AV1 with automatic metadata fetching from OMDb and TVmaze.
+
+## Build Commands
+
+```bash
+# Build binary
+go build -o videnc-vibe ./cmd/videnc/
+
+# Run binary
+./videnc-vibe
+
+# With flags
+./videnc-vibe -d              # Delete original after encode
+./videnc-vibe -c /path/to/config.yaml
+```
+
+## Code Style Guidelines
+
+### General
+- Use Go standard library; minimize external dependencies
+- Use `gopkg.in/yaml.v3` for YAML config parsing (already in go.mod)
+- Run `go fmt` and `go vet` before commits
+
+### Imports
+- Group imports: standard library, external packages, internal packages
+- Use aliases for packages: `"videnc-vibe/pkg/types"`
+
+```go
+import (
+    "fmt"
+    "os"
+
+    "gopkg.in/yaml.v3"
+    "videnc-vibe/pkg/types"
+)
+```
+
+### Naming
+- Packages: lowercase, single word (e.g., `encoder`, `metadata`)
+- Types: PascalCase (e.g., `Encoder`, `Job`)
+- Functions: PascalCase exported, camelCase unexported
+- Variables: camelCase
+- Constants: PascalCase for exported, camelCase for unexported
+- Acronyms: all caps for 2 letters (e.g., `IMDBID`), mixed for 3+ (e.g., `jpegImage`)
+
+### Error Handling
+- Return errors with context: `fmt.Errorf("parsing config: %w", err)`
+- Use sentinel errors for known conditions
+- Check errors explicitly, don't ignore with `_`
+
+### Types
+- Use specific types where appropriate (e.g., `MediaType` string type)
+- Define types in `pkg/types/types.go`
+
+### Functions
+- Keep functions small and focused
+- Prefer multiple small functions over large ones
+- Use receivers for methods: `func (e *Encoder) Transcode(...)`
+
+### Concurrency
+- Use channels for communication
+- Handle shutdown with context or done channels
+
+### Testing
+- Write tests in `*_test.go` files alongside implementation
+- Use table-driven tests for multiple cases
+- Test external dependencies with mocks
+
+### Commit Messages
+Follow Conventional Commits:
+- `add:` new features
+- `fix:` bug fixes
+- `refactor:` code restructuring
+- `chore:` maintenance
+
+Example: `add: add command line argument support`
+
+## Project Structure
+
+```
+cmd/videnc/main.go       # CLI entrypoint
+internal/
+  config/                # Config loading
+  watcher/               # Folder polling
+  encoder/               # FFmpeg wrapper
+  metadata/              # OMDb/TVmaze client
+  mover/                 # File operations
+  logger/                # Logging
+pkg/types/types.go       # Shared types
+```
+
+## Key Dependencies
+- `ffmpeg` - video encoding
+- `opusenc` - audio encoding
+- `gopkg.in/yaml.v3` - config parsing