---
name: run-teamforge
description: Build, run, and drive TeamForge. Use when asked to start TeamForge, run its tests, take a screenshot of its UI, verify a feature works, or interact with the running app.
---

TeamForge is a Django 6 club-management web app (members + teams). Drive it via `.claude/skills/run-teamforge/driver.mjs` under Playwright. The driver starts the dev server, creates a test superuser, logs in via `/admin/login/`, and screenshots any page.

All paths below are relative to the repo root (`/Users/bernard/Code/PycharmProjects/TeamForge/`).

## Prerequisites

Python (≥3.12) and `uv` must be present. Node.js (≥18) is required for the Playwright driver.

```bash
uv sync                  # install Python deps
npm install playwright   # install Playwright (one-time, at repo root)
npx playwright install chromium   # download Chromium browser (one-time, ~90 MB)
```

The app connects to a PostgreSQL database. Connection is in `.env`:

```
DJANGO_DATABASE_URL=postgres://...
DJANGO_DEBUG=True
```

If the database isn't reachable, the server still boots but all page requests fail with 500. The `.env` file must exist; there is no fallback to SQLite in production mode.

## Setup

```bash
uv sync
uv run python manage.py migrate   # apply migrations (idempotent)
```

## Run (agent path)

The driver handles everything — server startup, test-user creation, login, and screenshots.

```bash
# Smoke test: starts server, screenshots members + configuration pages
node .claude/skills/run-teamforge/driver.mjs smoke

# Screenshot any page (path or full URL)
node .claude/skills/run-teamforge/driver.mjs screenshot /backend/members/
node .claude/skills/run-teamforge/driver.mjs screenshot /backend/configuration

# Stop the background server
node .claude/skills/run-teamforge/driver.mjs stop
```

Screenshots land in `/tmp/teamforge-shots/<name>.png`. Server log → `/tmp/teamforge-server.log`.

Auth is via a local `skilltest` superuser (password: `skilltest123!`) which the driver creates automatically on first run. The driver logs in through `/admin/login/` — the app does not register `django.contrib.auth` URLs, so `/accounts/login/` returns 404.

## Run (human path)

```bash
uv run python manage.py runserver         # → http://localhost:8000
python manage.py tailwind start           # separate terminal — required for CSS
```

Log in at `/admin/login/` or create a superuser with `uv run python manage.py createsuperuser`.

## Test

```bash
uv run python manage.py test   # → 43 tests, all pass
```

---

## Gotchas

- **`/accounts/login/` returns 404** — the URL conf (`TeamForge/urls.py`) only has `backend/` and `admin/`. The `@login_required` decorator redirects there by default, but `django.contrib.auth.urls` is not included. Always log in via `/admin/login/`. The session cookie then works for all `/backend/` views.

- **`avatar` templatetag crashes on empty names** — `theme/templatetags/avatar.py:41` does `first_name[0]` which raises `IndexError: string index out of range` when either name field is blank. Every Django User used as a logged-in session must have `first_name` and `last_name` set. The driver sets them on the test user automatically.

- **`/backend/` dashboard is a placeholder** — `templates/backend/index.html` contains only "TEST FILE". This is expected during development; the real UI lives at `/backend/members/` and `/backend/configuration`.

- **Tailwind CSS not served in dev** — running `manage.py runserver` without `manage.py tailwind start` in a second terminal means pages render with no styles. The Playwright driver screenshots may look unstyled when Tailwind isn't running. For visual verification, start `tailwind start` first (or accept the unstyled capture).

- **PostgreSQL required** — `DJANGO_DATABASE_URL` in `.env` points to a remote PostgreSQL instance at `192.168.1.100`. If that host isn't reachable, every request returns 500. There is no in-repo SQLite fallback for normal runs; the test suite creates a separate test DB automatically.

- **`npm install playwright` must run at repo root** — the driver imports `playwright` via Node's resolution from `node_modules/` at the repo root. Running it from another directory will cause `ERR_MODULE_NOT_FOUND`.

## Troubleshooting

- **`Cannot find package 'playwright'`**: run `npm install playwright` at the repo root, then retry.
- **`Server did not start within 20s`**: check `/tmp/teamforge-server.log`. Most common cause: PostgreSQL unreachable (connection refused or timeout).
- **500 on every page after login**: the logged-in user has no `first_name`/`last_name` — the avatar templatetag crashes on the base template. Fix: set names on the user via `uv run python manage.py shell -c "from django.contrib.auth.models import User; u=User.objects.get(username='skilltest'); u.first_name='Skill'; u.last_name='Test'; u.save()"`.
- **`page.waitForURL` timeout on login**: admin login redirect failed — wrong password or user doesn't exist. The driver's `ensureTestUser()` recreates the user each run; if it fails, check that `manage.py shell` works at all.