# AGENTS.md

## Project
Heartbeat Monitor (`Next.js 15 + React 19`) for local website/app heartbeat tracking.

## Source Control Rules
- Never commit generated or dependency artifacts.
- Keep these ignored and untracked:
  - `.next/`
  - `node_modules/`
  - `out/`, `build/`, `dist/`
  - logs, local env files, OS files
- If generated folders are accidentally tracked again, untrack (keep local files):
  - `git rm -r --cached .next node_modules`

## Data Contract (Do Not Break)
- Persistence files:
  - `data/apps.json`
  - `data/status.json`
- Keep schema backward-compatible.
- Do not rename or remove existing keys used by API/UI without a migration plan.

## API Contract (Do Not Break)
- Endpoint: `src/app/api/monitor/route.ts`
- Supported actions:
  - `GET /api/monitor` returns `{ apps, status }`
  - `POST action=addApp`
  - `POST action=updateApp`
  - `POST action=deleteApp`
  - `POST action=recordStatus`

## UI/Product Guardrails
- UI must be responsive (mobile/tablet/desktop).
- Dashboard should prioritize scanability:
  - KPI summary
  - service health board
  - compact comparison table
  - recent incidents/events
- Keep live refresh behavior and avoid long single-column list regressions.

## Dev Workflow
- Start (port `3005`): `npm run dev -- --port 3005`
- Restart dev service:
  - In the running terminal: `Ctrl + C`
  - If port `3005` is busy: `lsof -ti :3005 | xargs kill`
  - Start again: `npm run dev -- --port 3005`
- Build check: `npm run build`
- Keep TypeScript build green before merging.