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

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.

2.4 KiB Raw Blame History