WatchLink/AGENTS.md

# Agent Instructions

## Project

WatchLink is a Dockerized Next.js + Postgres web app for persistent shared watch rooms. It supports local accounts, friend relationships, role and permission management, first-run admin setup, and synchronized playback for YouTube, Twitch, and direct video URLs.

## Repository Rules

- Use `codex-agent-repository-kit` conventions. This repository was initialized from `https://git.wilkensxl.de/MrSphay/codex-agent-repository-kit.git`.
- At the start of every task, check `git status --short --branch`. If an upstream remote exists and the working tree is clean, use a safe fast-forward pull.
- Preserve unrelated user changes. Do not rewrite history or run destructive git commands unless explicitly requested.
- Do not commit secrets, `.env` files, private keys, certificates, or tokens.
- Keep `.codex/project.md` aligned when commands, artifact paths, or release rules change.
- Do not create a release unless explicitly requested.
- Create focused tracker issues for real follow-up work that is outside the current scope or independently parallelizable. If Gitea issue access is unavailable, document the follow-up in `docs/agent-handoff.md`.
- Gitea target: `git.wilkensxl.de/MrSphay/WatchLink`.
- Docker image target: `git.wilkensxl.de/mrsphay/watchlink:latest`.

## Commands

```bash
npm install
npm run dev
npm run typecheck
npm run test
npm run build
npm run audit
npm run release:check
docker compose up --build
```

## Architecture Notes

- Next.js App Router lives under `src/app`.
- Shared UI components live under `src/components`.
- Domain helpers live under `src/lib`.
- Prisma schema lives in `prisma/schema.prisma`.
- The custom `server.js` hosts Next.js and Socket.IO at `/api/socket`.
- System theme is handled by CSS variables and `prefers-color-scheme`.

## Security Notes

- `NEXTAUTH_SECRET` must be changed in production.
- `DATABASE_URL` must not be committed outside `.env.example`.
- Passwords are hashed with bcrypt.
- Sessions are signed HTTP-only cookies.
- CI publishing uses `REGISTRY_TOKEN`; never commit it.

## Finish Checklist

- `git diff --check` passes.
- Run the cheapest reliable verification command available in the environment.
- Independent follow-up work has tracker issues, or `docs/agent-handoff.md` explains why issues could not be created.
- If a pushed Gitea workflow starts, poll it until success or report a concrete blocker.