docs: improve CLI documentation and argument handling

- Add comprehensive CLI Flags section to README with examples
- Update AGENTS.md with markdown conventions and cleanup
- Improve help text in main.go to show positional argument usage
- Add argument pre-processing to support minutes before flags

Author: topfunky

AGENTS.md

@@ -97,6 +97,10 @@ This is critical because:
 
 ## Code Patterns & Conventions
 
+### Markdown
+
+- Write all ordered lists starting with `1.`
+
 ### File Structure
 - Multiple `.go` files organized by responsibility (model, handlers, view, database, utils, constants)
 - All files are in the same package (main package)
@@ -133,25 +137,6 @@ This is critical because:
 - **Database tests**: Create temp SQLite DB in temp dir for isolation
 - **Time-based tests**: Use `testing.Testing()` to skip platform-specific code (e.g., macOS notifications)
 
-### Test Examples
-```go
-// Setup model with specific state
-m := model{
-  progress:       progress.New(...),
-  startTime:      time.Now().Unix(),
-  targetDuration: 3600,
-  countUpMode:    true,
-}
-
-// Trigger action
-newModel, cmd := m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'d'}})
-modelTyped := newModel.(model)
-
-// Assert outcomes
-assert.Equal(t, "", modelTyped.title, "Title should be blank after logging")
-assert.NoError(t, err)
-```
-
 ### Important: Test Always for User-Facing Changes
 - Any change to key handling must include key binding tests
 - Any change to UI rendering must verify View() output
@@ -255,22 +240,6 @@ Before submitting changes:
 - [ ] Error handling present and logged (don't silently fail)
 - [ ] JOURNAL.md updated for significant work
 
-## Dependencies
-
-### Core TUI Framework
-- `github.com/charmbracelet/bubbletea` v1.2.4+ - Event loop framework
-- `github.com/charmbracelet/bubbles` v0.20.0+ - UI components (progress, table)
-- `github.com/charmbracelet/lipgloss` v1.0.0+ - Terminal styling
-
-### Database
-- `github.com/mattn/go-sqlite3` v1.14.24+ - SQLite driver
-
-### Testing
-- `github.com/stretchr/testify` v1.10.0+ - Assertions and test helpers
-
-### Language
-- Go 1.23.4+ (check go.mod for exact version)
-
 ## Documentation
 
 - **JOURNAL.md**: Historical record of significant work (debugging, features, fixes)
@@ -280,24 +249,4 @@ Before submitting changes:
 - **README.md**: User-facing documentation (installation, usage, features)
 - **AGENTS.md** (this file): Developer guidelines for working in the codebase
 
-## Debugging Tips
-
-### Logging
-- Print errors with `fmt.Println()` - they appear in terminal
-- Use `fmt.Printf()` for debugging during development (remove before committing)
-- **Gotcha**: Error handling might hide issues - always check returned errors
-
-### Testing Specific Features
-```bash
-# Run single test
-go test -run TestCountUpModePromptLogAndReset -v
-
-# Run with timeout and race detector
-go test -race -timeout 30s -v
-```
 
-### Common Issues
-- **Panic on nil**: Always check error returns and nil assertions
-- **Timer seems wrong**: Verify `startTime` isn't being modified
-- **Database errors**: Check directory exists and file permissions
-- **UI not updating**: Verify `cmd := m.progress.SetPercent(...)` or `tea.Batch()` returns

README.md

@@ -5,7 +5,7 @@ A simple command-line application to run a [Pomodoro](https://www.pomodorotechni
 ## Features
 
 - Animated progress bar
-- Countdown timer
+- Countdown timer (defaults to `25` minutes)
 - Customizable timer duration
 
 ## Installation
@@ -47,6 +47,47 @@ Or specify a custom duration in minutes:
 tiny-timer 5
 ```
 
+## CLI Flags
+
+The following command-line flags are available:
+
+### Positional Arguments
+
+- **`[minutes]`** - Optional duration in minutes for the timer. If not specified, defaults to 25 minutes. Can be placed before or after flags.
+
+  ```bash
+  tiny-timer 5
+  tiny-timer -count-up 10
+  ```
+
+### Flags
+
+- **`-title <string>`** - Set an optional title for the timer session. Useful for labeling your work sessions.
+
+  ```bash
+  tiny-timer -title "Writing documentation"
+  tiny-timer 30 -title "Code review"
+  ```
+
+- **`-count-up`** - Enable count-up mode instead of countdown. In this mode, the timer tracks elapsed time and allows you to log tasks to the SQLite database. Default duration is 1 hour (for progress bar scaling).
+
+  ```bash
+  tiny-timer -count-up
+  tiny-timer -count-up -title "Project planning"
+  ```
+
+- **`-clean`** - Delete the SQLite database and exit. Useful for resetting your session history.
+
+  ```bash
+  tiny-timer -clean
+  ```
+
+- **`-debug`** - Enable debug logging to `debug.log` file. All log output will be written to this file for troubleshooting.
+
+  ```bash
+  tiny-timer -debug
+  ```
+
 ## Development
 
 ### Testing Releases with GoReleaser
@@ -76,14 +117,6 @@ For a full dry-run that also validates publishing (without actually publishing):
 goreleaser release --snapshot --skip-publish
 ```
 
-## Dependencies
-
-This project uses the following Go packages:
-
-- [github.com/charmbracelet/bubbles](https://github.com/charmbracelet/bubbles)
-- [github.com/charmbracelet/bubbletea](https://github.com/charmbracelet/bubbletea)
-- [github.com/charmbracelet/lipgloss](https://github.com/charmbracelet/lipgloss)
-
 ## License
 
 This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

main.go

@@ -25,6 +25,16 @@ func main() {
 	cleanFlag := flag.Bool("clean", false, "Delete the database and exit")
 	debugFlag := flag.Bool("debug", false, "Enable debug logging to debug.log")
 
+	// Customize usage to include positional argument
+	flag.Usage = func() {
+		fmt.Fprintf(os.Stderr, "Usage: %s [minutes] [flags]\n\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "Positional arguments:\n")
+		fmt.Fprintf(os.Stderr, "  minutes\n")
+		fmt.Fprintf(os.Stderr, "    \tDuration in minutes for the timer (default: 25)\n\n")
+		fmt.Fprintf(os.Stderr, "Flags:\n")
+		flag.PrintDefaults()
+	}
+
 	// Pre-process arguments to allow positional argument (minutes) before flags
 	// flag.Parse() stops at the first non-flag argument.
 	// We check if the first argument is a number and move it to the end if so.