# Repository Guidelines

## Project Structure & Module Organization
The Go entrypoint lives in `main.go`, delegating to packages inside `internal/`. `internal/config` loads JSON config, `internal/dl` wraps yt-dlp invocation, `internal/model` defines show metadata, and `internal/format`, `metadata`, `nfo`, and `scheduler` handle parsing, artwork, and task orchestration. Sample configuration, OPML exports, and binary artifacts are kept at the repo root (`config.json`, `youtube_subs.opml`, `subsyt`, `yt-dlp`). Treat `vids/` and `tmp/` as working directories; avoid checking large media into git.

## Build, Test, and Development Commands
- `CGO_ENABLED=0 go build -o subsyt`: produce the statically linked binary expected by downstream deployments.
- `go run . --config=/path/to/config.json`: execute against a config file; `CONFIG=/abs/config.json` also works.
- `go test ./...`: run package tests; add `-run TestName` when iterating locally.
- `go fmt ./... && go vet ./...`: format the tree and catch common correctness issues before review.

## Coding Style & Naming Conventions
Follow idiomatic Go style enforced by `gofmt`. Packages stay lowercase (`internal/dl`), exported types use `PascalCase`, and helpers remain unexported unless they serve multiple packages. Keep configuration fields aligned with the JSON schema in `internal/config`; when introducing new options, document both the struct tags and sample configs.

## Testing Guidelines
Write table-driven tests in `_test.go` files alongside the code under test, using Go’s standard `testing` package. Cover OPML parsing, identifier generation, and scheduler edge cases with realistic fixtures placed under `testdata/` (create it if missing). Target branch coverage for new logic, and ensure `go test ./...` passes without external network calls by mocking downloader interfaces.

## Commit & Pull Request Guidelines
Commits follow a Conventional Commits prefix (`fix:`, `refactor:`) in imperative mood, mirroring existing history (`git log --oneline`). Group related changes, and keep generated files out of the diff. Pull requests should summarize behavioural changes, note config schema updates, link to any tracking issues, and include before/after snippets or logs when touching downloader flows. Confirm the static binary still builds before requesting review.

## Configuration & External Tools
Document expected locations for `yt-dlp`, cookies, and OPML files when altering defaults. If a change requires bgutil or other external services, provide startup commands and update the sample `config.json`. Ensure new options degrade gracefully for existing configs and call out migration steps in the PR description.

## HTTP API
Enable the intake server with `http_api.enable` (binds to `127.0.0.1:4416`). Set `auth_token` or point `auth_token_file` at a mounted secret, and use `queue_file` to persist pending jobs. Example: `curl -H "Authorization: Bearer $TOKEN" -d '{"url":"https://youtu.be/ID","out_dir":"Channel"}' http://127.0.0.1:4416/v1/videos`. Inspect the queue with `curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:4416/status`.