# AGENTS.md

## Layout

- Current app is `backend/` (FastAPI) plus `frontend/` (Vite React); ignore Streamlit-era commands in `CONTRIBUTING.md`.
- Backend entrypoint: `backend/src/media_library_viewer_api/main.py` (`media_library_viewer_api.main:app`).
- Frontend entrypoint: `frontend/src/main.tsx`.
- Backend uses a `src/` layout; tests live in `backend/tests/`.

## Commands

- Backend setup: `cd backend && python -m venv .venv && source .venv/bin/activate && pip install -e '.[dev]'`
- Backend run: `uvicorn media_library_viewer_api.main:app --reload --port 8000`; if not installed, use `PYTHONPATH=src uvicorn media_library_viewer_api.main:app --reload --port 8000`.
- Backend tests: run `pytest` from `backend/`; focused checks can use `pytest tests/test_api.py` or `pytest -k <expr>`; if the package is not installed, use `PYTHONPATH=src pytest`.
- Frontend setup: `cd frontend && npm install`
- Frontend dev/build/lint: `npm run dev`, `npm run build`, `npm run lint`; `npm run build` already typechecks via `tsc -b`.
- Focused frontend typecheck: `npx tsc --noEmit`
- Local dev stack: `docker compose -f docker-compose.dev.yml up --build`
- Production stack: `docker compose up --build`

## Repo-Specific Gotchas

- Root compose files rely on environment-variable interpolation, not `env_file`; export required values before running them.
- Production compose needs the host/cert and OIDC variables from `docker-compose.yml` (`BACKEND_APP_HOST`, `FRONTEND_APP_HOST`, `CERT_RESOLVER`, and the frontend OIDC vars).
- Dev compose runs with auth off and does not need SSH key material unless you add remote SSH machines.
- `backend_cache` persists the media index and the managed `known_hosts` file.
- SSH host-key checking is strict, but the first successful connect records the host key into backend-managed `known_hosts`.
- Backend startup validates auth settings, rebuilds managed `known_hosts`, and starts the mail queue and backup alert poller.
- Machine-level settings now own Jellyfin/Jellyseerr/SSH config; the backend seeds a local machine automatically.
- Remote job templates live in `backend/src/media_library_viewer_api/jobs.py`; keep shell quoting intact.
- Backend Ruff config is in `backend/pyproject.toml` and uses line length 120 with Python 3.11.
- Update `docs/REQUIREMENTS.md` whenever behavior, UX, or architecture changes.
- Do not commit `.env`, `.streamlit/secrets.toml`, private keys, or tokens.