docs: add package docs and timer API comments

9 files changed, 30 insertions, 0 deletions

diff --git a/internal/cli/doc.go b/internal/cli/doc.go
new file mode 100644
index 0000000..c0e2c7e
--- /dev/null
+++ b/internal/cli/doc.go
@@ -0,0 +1,2 @@
+// Package cli wires Cobra commands for timer, worktime, and TUI entry points.
+package cli
diff --git a/internal/config/doc.go b/internal/config/doc.go
new file mode 100644
index 0000000..5d58f69
--- /dev/null
+++ b/internal/config/doc.go
@@ -0,0 +1,2 @@
+// Package config loads, saves, and defaults timr configuration values.
+package config
diff --git a/internal/duration/doc.go b/internal/duration/doc.go
new file mode 100644
index 0000000..9a99242
--- /dev/null
+++ b/internal/duration/doc.go
@@ -0,0 +1,2 @@
+// Package duration parses CLI duration values used by timr commands.
+package duration
diff --git a/internal/timefmt/doc.go b/internal/timefmt/doc.go
new file mode 100644
index 0000000..63afde5
--- /dev/null
+++ b/internal/timefmt/doc.go
@@ -0,0 +1,2 @@
+// Package timefmt parses timestamp inputs accepted by timr commands.
+package timefmt
diff --git a/internal/timer/doc.go b/internal/timer/doc.go
new file mode 100644
index 0000000..4edc233
--- /dev/null
+++ b/internal/timer/doc.go
@@ -0,0 +1,2 @@
+// Package timer provides persisted stopwatch operations and tracking helpers.
+package timer
diff --git a/internal/timer/operations.go b/internal/timer/operations.go
index 0653140..d49cb12 100644
--- a/internal/timer/operations.go
+++ b/internal/timer/operations.go
@@ -18,6 +18,7 @@ const trackCommandTimeout = 10 * time.Second
 
 type taskwarriorTracker struct{}
 
+// Track creates a Taskwarrior entry for tracked timer minutes.
 func (taskwarriorTracker) Track(description string, minutes int) error {
 	taskDescription := fmt.Sprintf("%dmin %s", minutes, description)
 	ctx, cancel := context.WithTimeout(context.Background(), trackCommandTimeout)
@@ -36,6 +37,7 @@ func (taskwarriorTracker) Track(description string, minutes int) error {
 	return nil
 }
 
+// StartTimer starts the timer, or continues an existing elapsed timer when requested.
 func StartTimer(continued bool) (string, error) {
 	state, err := LoadState()
 	if err != nil {
@@ -59,6 +61,7 @@ func StartTimer(continued bool) (string, error) {
 	return "Timer started.", nil
 }
 
+// StopTimer stops the running timer and persists elapsed time.
 func StopTimer() (string, error) {
 	state, err := LoadState()
 	if err != nil {
@@ -91,6 +94,7 @@ func getElapsed() (state State, elapsed time.Duration, err error) {
 	return state, elapsed, nil
 }
 
+// GetStatus returns a human-readable timer status summary.
 func GetStatus() (string, error) {
 	state, elapsed, err := getElapsed()
 	if err != nil {
@@ -104,6 +108,7 @@ func GetStatus() (string, error) {
 	return fmt.Sprintf("Status: Stopped\nElapsed Time: %s", elapsed.Round(time.Second)), nil
 }
 
+// ResetTimer resets persisted timer state to zero.
 func ResetTimer() (string, error) {
 	stateFile, err := GetStateFile()
 	if err != nil {
@@ -121,6 +126,7 @@ func ResetTimer() (string, error) {
 	return "Timer reset.", nil
 }
 
+// GetRawStatus returns elapsed time in seconds.
 func GetRawStatus() (string, error) {
 	_, elapsed, err := getElapsed()
 	if err != nil {
@@ -130,6 +136,7 @@ func GetRawStatus() (string, error) {
 	return fmt.Sprintf("%f", elapsed.Seconds()), nil
 }
 
+// GetRawMinutesStatus returns elapsed time in whole minutes.
 func GetRawMinutesStatus() (string, error) {
 	_, elapsed, err := getElapsed()
 	if err != nil {
@@ -139,6 +146,7 @@ func GetRawMinutesStatus() (string, error) {
 	return fmt.Sprintf("%d", int(elapsed.Minutes())), nil
 }
 
+// GetPromptStatus returns compact prompt-friendly timer output.
 func GetPromptStatus() (string, error) {
 	state, elapsed, err := getElapsed()
 	if err != nil {
@@ -157,10 +165,12 @@ func GetPromptStatus() (string, error) {
 	return fmt.Sprintf("%s%s", icon, elapsed.Round(time.Second)), nil
 }
 
+// TrackTime tracks elapsed timer time with the default tracker and resets state.
 func TrackTime(description string) (string, error) {
 	return TrackTimeWithTracker(description, taskwarriorTracker{})
 }
 
+// TrackTimeWithTracker tracks elapsed time using the provided tracker implementation.
 func TrackTimeWithTracker(description string, tracker Tracker) (string, error) {
 	if tracker == nil {
 		return "", errors.New("tracker is nil")
diff --git a/internal/timer/timer.go b/internal/timer/timer.go
index 0e29199..2a5dbde 100644
--- a/internal/timer/timer.go
+++ b/internal/timer/timer.go
@@ -12,6 +12,7 @@ const (
 	stateFile = ".timr_state"
 )
 
+// State stores persisted timer progress.
 type State struct {
 	StartTime   time.Time
 	ElapsedTime time.Duration
@@ -31,14 +32,17 @@ func resolveStateFilePath(path string) (string, error) {
 	return filepath.Join(configDir, "timr", stateFile), nil
 }
 
+// GetStateFile returns the default state file path.
 func GetStateFile() (string, error) {
 	return resolveStateFilePath("")
 }
 
+// LoadState loads timer state from the default state file.
 func LoadState() (State, error) {
 	return LoadStateAt("")
 }
 
+// LoadStateAt loads timer state from the provided path or default path when empty.
 func LoadStateAt(path string) (State, error) {
 	var state State
 	stateFilePath, err := resolveStateFilePath(path)
@@ -58,10 +62,12 @@ func LoadStateAt(path string) (State, error) {
 	return state, err
 }
 
+// Save writes timer state to the default state file.
 func (s *State) Save() error {
 	return s.SaveAt("")
 }
 
+// SaveAt writes timer state to the provided path or default path when empty.
 func (s *State) SaveAt(path string) error {
 	data, err := json.Marshal(s)
 	if err != nil {
diff --git a/internal/tui/doc.go b/internal/tui/doc.go
new file mode 100644
index 0000000..624b708
--- /dev/null
+++ b/internal/tui/doc.go
@@ -0,0 +1,2 @@
+// Package tui provides Bubble Tea models used by timr terminal interfaces.
+package tui
diff --git a/internal/worktime/doc.go b/internal/worktime/doc.go
new file mode 100644
index 0000000..410407d
--- /dev/null
+++ b/internal/worktime/doc.go
@@ -0,0 +1,2 @@
+// Package worktime stores work logs and builds aggregated report views.
+package worktime