diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..9a745101
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,44 @@
+# 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: `npm run dev`
+- Build check: `npm run build`
+- Keep TypeScript build green before merging.
diff --git a/PRD.md b/PRD.md
new file mode 100644
index 00000000..0553d262
--- /dev/null
+++ b/PRD.md
@@ -0,0 +1,140 @@
+# Product Requirements Document (PRD)
+
+## Product Name
+Heartbeat Monitor
+
+## Summary
+Heartbeat Monitor is a local-first dashboard for monitoring the health of locally hosted web apps/services. It surfaces uptime, incident events, and response-time behavior in a fast, scannable UI.
+
+## Problem Statement
+Developers running multiple local services need a single view to detect outages and latency issues quickly. A long, one-column list creates high cognitive load and slows triage.
+
+## Goals
+- Provide real-time visibility into service health for local apps.
+- Make status and incidents immediately scannable.
+- Preserve existing local JSON persistence and API workflows.
+- Support responsive usage across mobile, tablet, and desktop.
+
+## Non-Goals
+- Multi-user authentication/authorization.
+- External SaaS monitoring or cloud alert routing.
+- Replacing existing data schemas with breaking changes.
+
+## Target Users
+- Individual developers managing multiple local projects.
+- Small teams running local dev stacks on one machine.
+
+## Core Use Cases
+- View which services are up/down now.
+- See average uptime and response-time trends.
+- Inspect recent incidents/recoveries.
+- Add/remove monitors quickly.
+- Filter/search services for focused troubleshooting.
+
+## Functional Requirements
+1. Data Fetching
+- Poll monitor data from `/api/monitor` on an interval.
+- Allow manual refresh.
+
+2. Dashboard Views
+- KPI summary cards:
+  - healthy services
+  - average uptime
+  - average latency
+  - incident count
+- Service health board with per-service cards.
+- Service comparison table for fast row-based scanning.
+- Recent event feed and performance side panels.
+
+3. Service Operations
+- Add monitor via modal form.
+- Delete monitor with confirmation.
+
+4. Filtering and Search
+- Filter services by `all`, `healthy/up`, `down`.
+- Search by service name/category/description.
+
+5. Responsiveness
+- Mobile: stacked layout with horizontal overflow handling for table.
+- Tablet: multi-column cards.
+- Desktop: split board + right-side insight rail.
+
+## Data Model and Storage (Current Contract)
+### `data/apps.json`
+```json
+{
+  "apps": [
+    {
+      "id": "string",
+      "name": "string",
+      "description": "string",
+      "url": "string",
+      "port": 3000,
+      "path": "string",
+      "command": "string",
+      "category": "string",
+      "color": "#hex",
+      "enabled": true
+    }
+  ]
+}
+```
+
+### `data/status.json`
+```json
+{
+  "entries": [
+    {
+      "appId": "string",
+      "timestamp": "ISO-8601 string",
+      "status": "up | down",
+      "responseTime": 123
+    }
+  ]
+}
+```
+
+## API Requirements
+- Preserve endpoint: `src/app/api/monitor/route.ts`
+- Preserve actions:
+  - `addApp`
+  - `updateApp`
+  - `deleteApp`
+  - `recordStatus`
+- Preserve default GET payload shape: `{ apps, status }`
+
+## Technical Stack
+- Next.js 15 App Router
+- React 19
+- Tailwind CSS v4 (`@tailwindcss/postcss`)
+- Framer Motion
+- Recharts
+- Lucide icons
+
+## UX Principles
+- Scanability over decoration.
+- Clear status semantics (healthy/down/warning).
+- Dense information where needed (table), visual context where useful (cards/sparklines).
+- Fast interaction with minimal clicks.
+
+## Performance and Reliability Requirements
+- Keep polling lightweight and predictable.
+- Handle empty states gracefully.
+- Maintain type-safe data transformations.
+- Ensure production build passes (`npm run build`).
+
+## Success Metrics
+- Time-to-identify-down-service decreases.
+- Fewer clicks/scroll depth for common triage tasks.
+- Consistent layout quality across viewport sizes.
+
+## Risks
+- Schema drift if future edits break data compatibility.
+- UI regressions if responsive breakpoints are not validated.
+- Accidental commits of generated files if ignore rules are bypassed.
+
+## Open Future Enhancements
+- Incident duration timelines.
+- Per-service detail drawer.
+- Configurable polling interval.
+- Optional notifications/webhooks.