From 070a47e241d9ba7a51e2253fcbddf55a1941c765 Mon Sep 17 00:00:00 2001
From: Konstantin Fickel <mail@konstantinfickel.de>
Date: Sun, 29 Mar 2026 22:08:53 +0200
Subject: [PATCH] docs: add timesheet management documentation

Update README.md with:
- Repository configuration section for .streamd.toml
- Timesheet periods configuration example
- Description of timesheet report features

Update REQUIREMENTS.md with:
- R18a: Timesheet report configuration format
- R18b: Day type rules for expected/actual hours calculation
- R18c: Timesheet report warning types
- Updated R20 command description
---
 README.md       | 29 ++++++++++++++++++++++++++++-
 REQUIREMENTS.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 75 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 474663c..e2e0bcd 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,34 @@ Within files, `@`-prefixed markers at the beginning of paragraphs or headings de
 
 ## Configuration
 
-Streamd reads its configuration from `~/.config/streamd/config.toml` (XDG standard). The main setting is `base_folder`, which points to the directory containing your stream files (defaults to the current working directory).
+### User Configuration
+
+Streamd reads its user configuration from `~/.config/streamd/config.toml` (XDG standard). The main setting is `base_folder`, which points to the directory containing your stream files (defaults to the current working directory).
+
+### Repository Configuration
+
+For timesheet reporting, create a `.streamd.toml` file in your stream files directory:
+
+```toml
+timezone = "Europe/Berlin"  # Optional: timezone for day boundaries
+
+[timesheet]
+[[timesheet.periods]]
+start = "2026-01-01"
+end = "2026-06-30"
+hours_per_week = 38.0
+
+[[timesheet.periods]]
+start = "2026-07-01"
+end = "2026-12-31"
+hours_per_week = 40.0
+```
+
+The timesheet command will calculate expected vs actual working hours based on these periods, showing:
+- Daily breakdown with expected/actual hours
+- Special day types (sick leave, vacation, holidays, flex days)
+- Warnings for missing entries and overlapping timecards
+- Monthly and cumulative balance
 
 ## Usage
 
diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md
index 2ba44bd..04e8898 100644
--- a/REQUIREMENTS.md
+++ b/REQUIREMENTS.md
@@ -320,6 +320,52 @@ Process timesheet shards chronologically per day:
 
 **Validation:** The last entry of each day MUST be a `Break` (cannot end day while working).
 
+### R18a: Timesheet Report Configuration
+
+The `.streamd.toml` file in the base folder configures timesheet periods:
+
+```toml
+timezone = "Europe/Berlin"  # Optional timezone for day boundaries
+
+[timesheet]
+[[timesheet.periods]]
+start = "2026-01-01"
+end = "2026-06-30"
+hours_per_week = 38.0
+
+[[timesheet.periods]]
+start = "2026-07-01"
+end = "2026-12-31"
+hours_per_week = 40.0
+```
+
+**Configuration Rules:**
+- Dates use ISO 8601 format (`YYYY-MM-DD`)
+- Periods MUST NOT overlap (validation error if they do)
+- Gaps between periods are allowed — days in gaps have 0 expected hours
+- `hours_per_week` is distributed over Mon-Fri (e.g., 38h/week = 7.6h/day)
+
+### R18b: Day Type Rules
+
+| Day Type | Expected Hours | Actual Hours |
+|----------|---------------|--------------|
+| Regular work day | period.hours_per_week / 5 | Sum of timecards |
+| Weekend (Sat/Sun) | 0 | Sum of timecards (hidden if 0) |
+| Sick Leave (@SickLeave) | Normal expected | max(expected, worked) |
+| Vacation (@VacationDay) | Normal expected | expected + worked |
+| Holiday (@Holiday) | 0 | Sum of timecards |
+| Flex Day (@UndertimeDay) | Normal expected | 0 |
+| Day in gap (no period) | 0 | Sum of timecards + warning |
+| Missing (no entries) | Normal expected | 0 + warning |
+
+### R18c: Timesheet Report Warnings
+
+The report generates warnings for:
+
+1. **Missing days without explanation**: A weekday within a configured period has no timecard entries and no special day type marker
+2. **Overlapping timecards**: Two or more timecards on the same day have overlapping time ranges
+3. **Work outside configured periods**: Work logged on a day that falls outside all configured periods
+
 ---
 
 ## Query System
@@ -343,7 +389,7 @@ Provide recursive search through the shard tree:
 | `streamd new` | Create new timestamped file, open editor, rename with markers on close |
 | `streamd todo` | List all shards with `task: "open"` |
 | `streamd edit [n]` | Edit nth file (supports negative indexing for recent files) |
-| `streamd timesheet` | Extract and export timesheet data as CSV |
+| `streamd timesheet` | Generate formatted timesheet report with expected/actual hours |
 | `streamd completions <shell>` | Generate shell completions (bash, zsh, fish, elvish, powershell) |
 
 ---