# AGENTS.md

This file provides guidance for agents operating in the av1dae 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 av1dae ./cmd/av1dae/

# Run binary
./av1dae

# With flags
./av1dae -d              # Delete original after encode
./av1dae -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: `"av1dae/pkg/types"`

```go
import (
    "fmt"
    "os"

    "gopkg.in/yaml.v3"
    "av1dae/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/av1dae/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