# Agent instructions

Agents must use these ports.

## Port map

- 11100 — backend / API (Express). Default when `PORT` is unset. `npm start` listens here.
- 11110 — webpack-dev-server (`devServer.port` in `webpack.config.js`).

Vite is not configured in this repo. Any further listening service uses the next port in steps of 10 (11120, 11130, and so on).

## Dev loop

Use hot reload for feature work, pull requests, and when loading a branch onto this desktop. `npm run dev` runs nodemon and webpack-dev-server with hot reload (API on 11100, assets on 11110). Do not run a production build for that work. Run the production build only when pushing to master.

## Tests

After a major change to the API, run `npm test`. Small edits do not need a test run.

## Questions

Answer questions in this chat.

## Finished work

When a task is finished, merge its PR into the primary branch this work is based on. That branch is `master` unless the work was started from another branch. Do not wait to be asked. Do not force-push. The production build runs only on that merge to `master`, not while the PR is in progress.

## Cloud preview

This repository has automatic branch-specific Cloudflare preview URLs.

Preview configuration:
`.cursor/preview.json`

Preview helper:
`./.cursor/scripts/preview.sh`

### On startup

Cursor Cloud startup should normally run the preview helper automatically.

If the configured services or preview tunnel are not running, run:

`./.cursor/scripts/preview.sh`

### After changing branches

Whenever you checkout, switch, create, rename, or otherwise change the current git branch, rerun:

`./.cursor/scripts/preview.sh`

The preview URLs are derived from the current branch.

### Finding the current preview URLs

If you do not know the preview URLs, run:

`./.cursor/scripts/preview.sh --urls`

This only calculates and prints the URLs. It does not start services or modify Cloudflare.

Do not guess preview URLs when this command is available.

### Services

Every publicly exposed service must have an explicit service name in `.cursor/preview.json`.
There is no default service.

When adding a publicly previewable service, add its `name`, `port`, `cwd`, and `command` to `.cursor/preview.json`, then rerun the preview helper.

Do not create ad-hoc `trycloudflare.com` Quick Tunnels.

When reporting completed browser-visible work, include the relevant preview URL(s).