docs: update README with features and design notes; add NEXT_STEPS

README now covers features list, run instructions, design rationale
(integer money/duration, read-time cost resolution, soft budget
enforcement, Flyway-only schema, API shape).

NEXT_STEPS.md catalogs deferred work: user CRUD UI, rate snapshots,
notes field, CSV export, auth, pagination, Playwright e2e, i18n,
dark mode, bookmarkable URLs, full backend test pyramid.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

README.md

@@ -1,6 +1,19 @@
-# App
+# Time Tracker
 
-React 19 + Spring Boot 3.4 web app backed by PostgreSQL 17.
+A browser-based time-tracking app: log daily work against projects, review totals in weekly and
+monthly views, and track project budgets with automatic cost calculation and soft breach warnings.
+
+**Stack:** React 19 + Vite 6 (TypeScript strict) — Spring Boot 3.4 (Java 21) — PostgreSQL 17 via
+Docker Compose — Flyway for schema migrations — Tailwind CSS v4 — Biome 1.9 — Vitest.
+
+## Features
+
+- **Daily time entries** — date, project, duration (entered as h:mm), automatic cost from hourly rate
+- **Weekly view** — navigate by ISO week; see total hours per day and a running week total
+- **Monthly view** — per-project summary with time and cost progress bars; red banner when a budget is exceeded
+- **Project management** — create projects with time and cost budgets; set a project-level hourly rate or fall back to the user's default
+- **Multi-user** — pick any seeded user from the dropdown; cost is calculated using that user's rate when no project rate is set
+- **Soft budget enforcement** — entries always save; over-budget projects are highlighted with a warning banner and colored bars
 
 ## Quick start
 
@@ -43,6 +56,26 @@ mvn -f backend/pom.xml test -q
 cd frontend && npx vitest run
 ```
 
+## Design notes
+
+**Money and duration** are stored as integers (cents and minutes respectively) to avoid floating-point
+drift. Cost for a time entry is computed at read time: `duration_minutes × effective_rate_cents / 60`,
+where the effective rate is the project's `hourly_rate_cents` if set, otherwise the user's
+`default_hourly_rate_cents`. This means changing a rate retroactively updates all historical cost
+totals — a deliberate trade-off for simplicity (see `NEXT_STEPS.md` for a snapshot-based alternative).
+
+**Budget warnings** are soft: any entry saves regardless of budget status. Breach is detected in the
+reporting layer by comparing aggregated totals to the project's `time_budget_minutes` and
+`cost_budget_cents`. The monthly view renders a red warning banner and saturated progress bars for
+any over-budget project.
+
+**Schema migrations** are managed exclusively by Flyway (`V1__init.sql` for schema, `V2__seed_demo_data.sql`
+for demo users and projects). Hibernate is set to `validate` — it never modifies the schema.
+
+**API shape** — aggregation is done server-side via two dedicated endpoints:
+`GET /api/reports/weekly?userId=&week=YYYY-Www` and `GET /api/reports/monthly?userId=&month=YYYY-MM`.
+All other CRUD endpoints follow standard REST conventions under `/api/`.
+
 ## Environment
 
 `.env.example` documents all env vars. `mise run setup` copies it to `.env` automatically on first run.