diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
new file mode 100644
index 0000000..6df1e47
--- /dev/null
+++ b/.planning/REQUIREMENTS.md
@@ -0,0 +1,114 @@
+# Requirements: Kimai Heatmap Plugin
+
+**Defined:** 2026-04-08
+**Core Value:** At a glance, see where your time went — a visual map of tracking activity that makes patterns obvious
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Dev Environment
+
+- [ ] **DEV-01**: Nix flake/devshell provides a running local Kimai instance
+- [ ] **DEV-02**: Local Kimai has a seeded database with realistic time entry data
+- [ ] **DEV-03**: Plugin is loadable in the local Kimai instance for manual testing
+
+### Plugin Scaffold
+
+- [ ] **PLUG-01**: Plugin is a valid Symfony bundle discoverable by Kimai
+- [ ] **PLUG-02**: Plugin registers a dashboard widget visible on the Kimai dashboard
+- [ ] **PLUG-03**: Plugin ships a backend API endpoint returning aggregated daily time data
+
+### Heatmap Core
+
+- [ ] **HEAT-01**: Widget renders a d3.js calendar heatmap (weeks x days grid)
+- [ ] **HEAT-02**: Cell color intensity reflects hours tracked per day (darker = more)
+- [ ] **HEAT-03**: Hovering a cell shows tooltip with date, hours, and entry count
+- [ ] **HEAT-04**: Day-of-week labels (Mon/Wed/Fri) on Y-axis
+- [ ] **HEAT-05**: Month labels along the top showing month boundaries
+- [ ] **HEAT-06**: Empty days render with a distinct "no data" color
+- [ ] **HEAT-07**: Clicking a day cell navigates to Kimai timesheet view filtered to that date
+- [ ] **HEAT-08**: Color scheme uses Kimai's theme CSS variables
+
+### Interactivity
+
+- [ ] **INTR-01**: Dropdown filter to view heatmap for a specific project or activity
+
+### Polish
+
+- [ ] **POLI-01**: Streak indicator showing current consecutive days with tracked time
+- [ ] **POLI-02**: Summary stats row (total hours, average hours/day, busiest day)
+- [ ] **POLI-03**: Visual distinction for weekend days (subtle border or opacity)
+
+### Testing
+
+- [ ] **TEST-01**: PHPUnit tests for the data aggregation service (timezone-correct day grouping)
+- [ ] **TEST-02**: PHPUnit tests for the API endpoint (response format, filtering)
+- [ ] **TEST-03**: JavaScript tests for d3 heatmap rendering (grid structure, color mapping)
+- [ ] **TEST-04**: JavaScript tests for tooltip and click interaction behavior
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### Interactivity
+
+- **INTR-02**: Toggle between hours-per-day and entry-count display modes
+- **INTR-03**: Configurable time range selector (3 months, 6 months, year, custom)
+
+### Polish
+
+- **POLI-04**: Responsive widget sizing adapting to dashboard column width
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Billable vs non-billable split | Personal time tracking, not client billing |
+| Real-time / live updates | Page reload sufficient for daily-granularity data |
+| Export/share heatmap as image | No audience for personal use |
+| Hour-of-day matrix | Different visualization, scope creep |
+| Drill-down charts in widget | Click-through to Kimai views instead |
+| Multi-user comparison | Personal tracking tool |
+| Goal setting / targets | Streak indicator covers motivation simply |
+| Animated transitions | Complexity for near-zero utility |
+| Mobile-specific layout | Desktop Kimai dashboard only |
+| Custom color theme picker | Kimai theme integration is sufficient |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| DEV-01 | TBD | Pending |
+| DEV-02 | TBD | Pending |
+| DEV-03 | TBD | Pending |
+| PLUG-01 | TBD | Pending |
+| PLUG-02 | TBD | Pending |
+| PLUG-03 | TBD | Pending |
+| HEAT-01 | TBD | Pending |
+| HEAT-02 | TBD | Pending |
+| HEAT-03 | TBD | Pending |
+| HEAT-04 | TBD | Pending |
+| HEAT-05 | TBD | Pending |
+| HEAT-06 | TBD | Pending |
+| HEAT-07 | TBD | Pending |
+| HEAT-08 | TBD | Pending |
+| INTR-01 | TBD | Pending |
+| POLI-01 | TBD | Pending |
+| POLI-02 | TBD | Pending |
+| POLI-03 | TBD | Pending |
+| TEST-01 | TBD | Pending |
+| TEST-02 | TBD | Pending |
+| TEST-03 | TBD | Pending |
+| TEST-04 | TBD | Pending |
+
+**Coverage:**
+- v1 requirements: 22 total
+- Mapped to phases: 0
+- Unmapped: 22 ⚠️
+
+---
+*Requirements defined: 2026-04-08*
+*Last updated: 2026-04-08 after initial definition*