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/.

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
Solo landing: after review and verification, squash-land a feature branch with bash scripts/land-branch.sh <feature-branch> "<conventional commit message>"; do not commit directly on main.

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.