feat(cli): add detailed calendar reporting

add a new calendar detailed command with day-by-day events, day-off\nreasons, and celebrations\n\nadd a global --duration-format flag for minute-based read output\n(minutes, hours, days, hhmm) across worktimes, absence, saldo,\nholidays, and calendar commands\n\nupdate help text, docs, and skill guidance to state that worktimes\ncommands are worktime-only and to prefer calendar detailed/overview\nfor full schedule interpretation

Author: mekedron

README.md

@@ -7,8 +7,9 @@ It is intended for Finnish time tracking use cases.
 
 - auth command (`otta auth login`)
 - status check command (`otta status`)
+- cumulative saldo command (`otta saldo`)
 - worktime commands (`list/browse/report/options/add/update/delete`)
-- calendar overview command (`otta calendar overview`)
+- calendar commands (`overview/detailed`)
 - holidays retrieval command
 - absence commands (`options/browse/comment`)
 - configurable local config path
@@ -67,13 +68,35 @@ otta worktimes list --date 2026-02-20
 otta worktimes browse --from 2026-02-20 --to 2026-02-26 --format json
 otta worktimes report --from 2026-02-01 --to 2026-02-28 --format csv
 otta calendar overview --from 2026-02-01 --to 2026-02-28 --format json
+otta calendar detailed --from 2026-02-01 --to 2026-02-28 --format json
 otta worktimes options --date 2026-02-20 --format json
+otta saldo --format json
 otta holidays --from 2026-02-20 --to 2026-02-20 --worktimegroup <id> --format json
 otta absence browse --from 2026-02-01 --to 2026-02-28 --format json
 otta absence options --format json
 otta absence comment --type sick --from 2026-02-20 --to 2026-02-20
 ```
 
+Important: `worktimes list/browse/report` return only worktime rows and do not include absences.
+For full day-by-day schedule checks (worktimes + absences + holidays/day-off signals), prefer:
+
+```bash
+otta calendar detailed --from 2026-02-01 --to 2026-02-28 --format json
+```
+
+Duration conversion on read commands:
+
+- Global flag: `--duration-format` with values `minutes` (default), `hours`, `days`, `hhmm`
+- Works across read commands that expose minute totals (`worktimes`, `absence browse`, `saldo`, `holidays`, `calendar overview`, `calendar detailed`)
+- Day conversion uses a fixed basis: `1 day = 24 hours = 1440 minutes`
+- Example:
+
+```bash
+otta calendar detailed --from 2026-02-01 --to 2026-02-28 --duration-format hours
+otta worktimes browse --from 2026-02-01 --to 2026-02-28 --format json --duration-format days
+otta absence browse --from 2026-02-01 --to 2026-02-28 --format json --duration-format hhmm
+```
+
 For non-interactive scripts, prefer stdin or env secrets to reduce shell history exposure:
 
 ```bash
@@ -110,8 +133,8 @@ Credential env vars:
 - `OTTA_CLI_TOKEN_TYPE`
 - `OTTA_CLI_REFRESH_TOKEN`
 - `OTTA_CLI_TOKEN_SCOPE`
-- `OTTA_CLI_USER_ID` (optional convenience for `worktimes add`)
-- `OTTA_CLI_WORKTIMEGROUP_ID` (optional convenience for `holidays` and `calendar overview`)
+- `OTTA_CLI_USER_ID` (optional convenience for `worktimes add` and `saldo`)
+- `OTTA_CLI_WORKTIMEGROUP_ID` (optional convenience for `holidays`, `calendar overview`, and `calendar detailed`)
 
 ## Test and Lint
 

docs/cli-auth.md

@@ -51,7 +51,7 @@ otta auth login --username <username> --password "$OTTA_CLI_PASSWORD"
 `otta auth login` stores credentials/token in local config.
 API-derived profile data is stored in a separate cache file.
 `otta status` refreshes cached user metadata (`user.id`, `worktimegroup_id`) used by
-`worktimes add`, `holidays`, and `calendar overview` fallback resolution.
+`worktimes add`, `holidays`, `calendar overview`, and `calendar detailed` fallback resolution.
 
 Any authenticated command uses silent token renewal when possible:
 

docs/cli-installation.md

@@ -58,8 +58,12 @@ $OTTA_BIN config path
 $OTTA_BIN config cache-path
 $OTTA_BIN absence browse --from 2026-02-01 --to 2026-02-28 --format json
 $OTTA_BIN calendar overview --from 2026-02-01 --to 2026-02-28 --format json
+$OTTA_BIN calendar detailed --from 2026-02-01 --to 2026-02-28 --format json --duration-format hours
 ```
 
+Note: `worktimes` commands are worktime-only and do not return absences.
+Minute-based read commands support `--duration-format minutes|hours|days|hhmm`.
+
 ## Next Steps
 
 1. [Authentication](./cli-auth.md)

docs/cli-output-contract.md

@@ -12,8 +12,10 @@ For scriptability, command output is deterministic.
 - JSON mode with `--format json` is available on:
   - `auth login`
   - `status`
+  - `saldo`
   - all `worktimes` subcommands
   - `calendar overview`
+  - `calendar detailed`
   - `holidays`
   - `absence options`
   - `absence browse`
@@ -31,6 +33,21 @@ For scriptability, command output is deterministic.
 - top-level object: `ok`, `command`, `data`
 - `data` fields are command-specific
 - raw API payload is included where API schemas vary by tenant
+- `worktimes list/browse/report` payloads are worktime-only and never include absences
+- use `absence browse` or `calendar detailed/overview` when absence-aware schedule output is needed
+- minute-based read commands support global `--duration-format` (`minutes|hours|days|hhmm`)
+- duration conversion basis for `days` is fixed: `1 day = 24h = 1440 minutes`
+
+## Duration Fields
+
+When a command includes minute totals, JSON responses include:
+
+- `duration_format`: normalized selected format
+- duration summary objects (for example `total_duration`, `worktime_duration`, `absence_duration`, or `durations.*`) with:
+  - `format`
+  - `minutes` (raw canonical value)
+  - `value` (converted value)
+  - `text` (human-readable representation)
 
 Example (`worktimes list`):
 
@@ -77,7 +94,14 @@ Example (`absence browse`, excerpt):
     "to": "2026-02-28",
     "days": 28,
     "count": 1,
-    "total_minutes": 450
+    "total_minutes": 450,
+    "duration_format": "hours",
+    "total_duration": {
+      "format": "hours",
+      "minutes": 450,
+      "value": 7.5,
+      "text": "7.50 hours"
+    }
   }
 }
 ```
@@ -100,6 +124,45 @@ Example (`calendar overview`, excerpt):
 }
 ```
 
+Example (`calendar detailed`, excerpt):
+
+```json
+{
+  "ok": true,
+  "command": "calendar detailed",
+  "data": {
+    "from": "2026-02-01",
+    "to": "2026-02-28",
+    "worktime_group_id": 17910737,
+    "totals": {
+      "day_off_days": 8,
+      "celebration_days": 0
+    }
+  }
+}
+```
+
+Example (`saldo`, excerpt):
+
+```json
+{
+  "ok": true,
+  "command": "saldo",
+  "data": {
+    "user_id": 24352445,
+    "from": "2024-09-01",
+    "to": "2026-02-21",
+    "cumulative_saldo_minutes": 1463,
+    "cumulative_saldo_duration": {
+      "format": "hours",
+      "minutes": 1463,
+      "value": 24.3833,
+      "text": "24.38 hours"
+    }
+  }
+}
+```
+
 ## Error Output
 
 - errors are returned as plain text on `stderr`

docs/cli-overview.md

@@ -31,6 +31,7 @@ otta status
 - `otta --version`: print CLI build version.
 - `otta auth login`: authenticate and store token/config data.
 - `otta status`: validate auth and refresh cached user/worktimegroup metadata.
+- `otta saldo`: return current cumulative saldo for the resolved user id.
 - `otta config path`: print resolved config path.
 - `otta config cache-path`: print resolved cache path.
 - `otta worktimes list`: list entries for a specific date.
@@ -40,30 +41,54 @@ otta status
 - `otta worktimes add`: create an entry.
 - `otta worktimes update`: update an existing entry.
 - `otta worktimes delete`: delete an entry.
-- `otta calendar overview`: generate combined day-by-day report (worktimes + absences + holidays).
+- `otta calendar overview`: generate combined calendar totals with day rows.
+- `otta calendar detailed`: generate full day-by-day detailed calendar report.
 - `otta holidays`: fetch workday calendar/holiday rows.
 - `otta absence options`: fetch absence type/user options.
 - `otta absence browse`: aggregate absence entries across a date range.
 - `otta absence comment`: generate absence comment text.
 
+Important: `worktimes list/browse/report` do not return absences.
+For complete schedule interpretation, prefer `calendar detailed` (or `calendar overview` for lighter totals/day rows).
+
+## Duration Formatting
+
+Use global `--duration-format` on read commands with minute totals:
+
+- values: `minutes` (default), `hours`, `days`, `hhmm`
+- applies to: `worktimes list/browse/report`, `absence browse`, `saldo`, `holidays`, `calendar overview`, `calendar detailed`
+- conversion basis for `days`: `1 day = 24h = 1440 minutes`
+
+Examples:
+
+```bash
+otta worktimes browse --from 2026-02-01 --to 2026-02-28 --format json --duration-format hours
+otta saldo --format json --duration-format hhmm
+otta calendar detailed --from 2026-02-01 --to 2026-02-28 --format json --duration-format hhmm
+```
+
 ## Practical First-Run Sequence
 
 ```bash
 otta auth login --username <username> --password <password>
 otta status --format json
 otta worktimes options --date 2026-02-20 --format json
+otta saldo --format json
 otta worktimes list --date 2026-02-20 --format json
 otta absence browse --from 2026-02-01 --to 2026-02-28 --format json
 otta calendar overview --from 2026-02-01 --to 2026-02-28 --format json
+otta calendar detailed --from 2026-02-01 --to 2026-02-28 --format json
 ```
 
 ## Validation Note
 
 A real terminal E2E sweep was run on 2026-02-22 against the live API, covering:
 
 - auth and status
+- saldo
 - config path commands
 - worktimes list/browse/report/options/add/update/delete
 - calendar overview
+- calendar detailed
 - holidays
 - absence options/browse/comment

docs/cli-roadmap.md

@@ -8,6 +8,7 @@ sidebar_position: 6
 
 - Added `absence browse` range command (`/ttapi/absence/split`).
 - Added `calendar overview` combined day-by-day report (worktimes + absences + holidays).
+- Added `calendar detailed` full day-by-day report with day-off reasons and celebrations.
 
 ## Next
 

docs/cli-timesheets.md

@@ -11,6 +11,15 @@ Before running these commands:
 
 ## Worktimes
 
+Important: `worktimes list`, `worktimes browse`, and `worktimes report` return only worktime rows.
+They do not include absences. Use `absence browse` or `calendar detailed` when schedule context matters.
+
+Duration display on read commands can be changed with global `--duration-format`:
+
+- supported formats: `minutes` (default), `hours`, `days`, `hhmm`
+- `days` uses fixed conversion `1 day = 24h = 1440 minutes`
+- for AI schedule analysis, prefer `calendar detailed --format json --duration-format <format>`
+
 Collect worktimes for a day:
 
 ```bash
@@ -122,6 +131,27 @@ Fallback order for `--worktimegroup`:
 - `OTTA_CLI_WORKTIMEGROUP_ID`
 - cached user profile (`~/.otta-cli/cache.json` by default)
 
+## Saldo
+
+Fetch current cumulative saldo:
+
+```bash
+otta saldo --format json
+```
+
+Optional explicit user id:
+
+```bash
+otta saldo --user <user-id> --format json
+```
+
+If `--user` is omitted in `saldo`, fallback order is:
+
+- `OTTA_CLI_USER_ID`
+- cached user profile (`~/.otta-cli/cache.json` by default)
+
+`saldo` also supports `--duration-format` for converted saldo output.
+
 ## Absences
 
 Browse absences across a date range (calendar-compatible split rows):
@@ -150,7 +180,15 @@ otta calendar overview --from 2026-02-01 --to 2026-02-28 --format json
 
 `calendar overview` returns one `items[]` row per day in range, including weekends and days without entries.
 
-If `--worktimegroup` is omitted for `calendar overview`, fallback order is:
+Generate detailed calendar view (day-by-day with events, day-off reasons, and celebrations):
+
+```bash
+otta calendar detailed --from 2026-02-01 --to 2026-02-28 --format json
+```
+
+For AI/automation schedule checks, prefer `calendar detailed --format json` first.
+
+If `--worktimegroup` is omitted for `calendar overview` or `calendar detailed`, fallback order is:
 
 - `OTTA_CLI_WORKTIMEGROUP_ID`
 - cached user profile (`~/.otta-cli/cache.json` by default)

internal/cli/absence_browse_command.go

@@ -28,6 +28,10 @@ func newAbsenceBrowseCommand() *cobra.Command {
 			if err != nil {
 				return err
 			}
+			durationFormat, err := resolveDurationFormat(cmd)
+			if err != nil {
+				return err
+			}
 
 			fromDate, toDate, err := parseWorktimesDateRange(dateFrom, dateTo)
 			if err != nil {
@@ -54,15 +58,17 @@ func newAbsenceBrowseCommand() *cobra.Command {
 					OK:      true,
 					Command: "absence browse",
 					Data: map[string]any{
-						"from":          report.From,
-						"to":            report.To,
-						"days":          report.Days,
-						"count":         report.Count,
-						"total_minutes": report.TotalMinutes,
-						"total_hours":   report.TotalHours,
-						"items":         report.Items,
-						"responses":     report.Responses,
-						"raw":           report.Raw,
+						"from":            report.From,
+						"to":              report.To,
+						"days":            report.Days,
+						"count":           report.Count,
+						"total_minutes":   report.TotalMinutes,
+						"total_hours":     report.TotalHours,
+						"duration_format": durationFormat,
+						"total_duration":  durationSummary(report.TotalMinutes, durationFormat),
+						"items":           report.Items,
+						"responses":       report.Responses,
+						"raw":             report.Raw,
 					},
 				})
 			}
@@ -73,6 +79,7 @@ func newAbsenceBrowseCommand() *cobra.Command {
 			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "entries: %d\n", report.Count)
 			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "total_minutes: %d\n", report.TotalMinutes)
 			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "total_hours: %.2f\n", report.TotalHours)
+			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "total_duration: %s\n", formatDurationForText(report.TotalMinutes, durationFormat))
 			_, _ = fmt.Fprintln(cmd.OutOrStdout(), "use --format json for full payload")
 			return nil
 		},

internal/cli/calendar_command.go

@@ -11,6 +11,7 @@ func newCalendarCommand() *cobra.Command {
 		},
 	}
 
+	calendarCmd.AddCommand(newCalendarDetailedCommand())
 	calendarCmd.AddCommand(newCalendarOverviewCommand())
 	return calendarCmd
 }