# AGENTS.md

Guidance for AI coding agents working in this repository.

## Project Shape

- `fetch_contests.py` is the data generator. It fetches contests, normalizes records with `platform`, `title`, `start_time`, `end_time`, `status`, and `url`, then writes `contests_all.json` in the repository root.
- Current contest providers are Codeforces, AtCoder, UOJ, and Nowcoder.
- `.github/workflows/deploy.yml` is the GitHub Actions automation. It installs Python dependencies, runs `fetch_contests.py`, and commits generated JSON changes.
- `server/index.php` is the serving/display layer. It reads the public raw `contests_all.json`, caches it locally, and renders upcoming plus recently finished contests.
- User-facing documentation lives in [README.md](README.md) and [README_zh.md](README_zh.md). Keep both languages in sync.

## Actions vs Server Responsibilities

- Actions side: update contest data only. Change `.github/workflows/deploy.yml` when editing schedule triggers, Python version, dependency installation, generated files to commit, or commit/push behavior.
- Data-fetch side: change `fetch_contests.py` when editing providers, normalization, filtering, output JSON shape, or output file policy.
- Server side: change `server/index.php` when editing presentation, caching, raw JSON URL, platform labels/classes, countdown behavior, or PHP deployment behavior. The current page requires PHP 5.4 or newer.
- Server localization: `server/index.php` detects browser/system language and time zone, syncs them to cookies, and uses those cookies for first-render localized text and contest times.
- Do not put scraping logic in `server/index.php`; keep upstream fetching in `fetch_contests.py` so Actions can generate static JSON.

## Adding or Removing a Contest Provider

When adding a new contest provider, check all relevant surfaces:

- `fetch_contests.py`: add a `fetch_<provider>()` function, normalize records through `make_contest()`, add it to both output flows in `main()`, and preserve `status` semantics.
- `server/index.php`: add the platform name to `$platform_class` and define a matching `.platform.<class>` CSS rule if the provider appears in `contests_all.json`.
- `README.md` and `README_zh.md`: update supported platforms, data-source notes, and any changed usage/output details.
- `AGENTS.md`: update this guidance if the provider introduces a new pattern, dependency, output contract, or operational caveat.
- `.github/workflows/deploy.yml`: update only if the provider needs new Python dependencies, generated files, secrets, or schedule behavior.

When removing a provider, remove or adjust the same surfaces so stale platform labels, CSS classes, docs, and workflow dependencies do not remain.

## Output Contracts

- `contests_all.json` is an object with `generated_at` and `contests`; `contests` contains contests that have not ended yet (`upcoming` and `running`) plus contests that finished within the last 30 days.
- JSON timestamps are Unix timestamps in seconds.
- Keep record keys stable unless the README files and server rendering are updated in the same change.

## Validation

Do not proactively create a Python virtual environment unless the user asks for one. Run Python commands directly with `python`.

After changing fetching, filtering, output shape, provider support, or workflow-generated files, run:

```bash
python fetch_contests.py
```

Then inspect the generated files with `jq` when available, for example:

```bash
jq '.contests | group_by(.status) | map({status: .[0].status, count: length})' contests_all.json
```

For PHP-only presentation changes, also check that `server/index.php` still reads `contests_all.json` and handles unknown platforms with the default styling.

## Documentation Rule

Every feature addition, feature removal, provider change, output contract change, or workflow behavior change must update all three documentation files in the same change:

- [README.md](README.md)
- [README_zh.md](README_zh.md)
- [AGENTS.md](AGENTS.md)

Link to existing docs instead of duplicating long explanations. Keep agent guidance concise and operational.