docs: move project description to README, point AGENTS.md to it

2026-05-28 11:59:12 +02:00 · 2026-05-28 11:59:12 +02:00 · 17e6a35b37
commit 17e6a35b37
parent 2d60624e0e
3 changed files with 196 additions and 84 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,114 @@
+# Timesheets
+
+A Python CLI tool that parses markdown pipe-delimited timesheet tables and
+exports them to CSV for import into Odoo. It also supports a human-readable
+summary view, a stories list, a work status dashboard, and can fetch notes
+directly from Joplin.
+
+## Package layout
+
+```
+timesheets/
+├── pyproject.toml                  # package metadata, entry point, dev dependencies
+├── timesheets.example.toml         # example config file
+└── src/timesheets/
+    ├── cli.py        # argument parsing, main() entry point
+    ├── parser.py     # markdown table parsing, aggregation, date filtering
+    ├── projects.py   # project_map.json loading and key resolution
+    ├── output.py     # CSV writing, summary, stories, and status printing
+    ├── config.py     # TOML config file loading and key extraction
+    ├── joplin.py     # Joplin API integration (notebook traversal, note fetching)
+    ├── status.py     # day/week status calculations
+    └── utils.py      # shared low-level helpers (duration parsing, formatting, etc.)
+```
+
+## Installation
+
+```sh
+cd timesheets
+uv sync
+```
+
+## Subcommands
+
+| Command | Description |
+|---|---|
+| `summary` | Human-readable summary of time spent per project |
+| `csv` | Export timesheet entries as CSV for Odoo import |
+| `stories` | List stories worked on, grouped by project |
+| `status` | Show hours remaining today and projected week total |
+
+All subcommands accept the same source and day arguments:
+
+```sh
+# Source: Joplin (recommended) or a local file
+uv run timesheets <cmd> --joplin
+uv run timesheets <cmd> --input timesheet.md
+
+# Day: defaults to today, accepts YYYY-MM-DD, MM-DD, natural language
+uv run timesheets <cmd> 2026-05-22 --joplin
+uv run timesheets <cmd> yesterday --joplin
+uv run timesheets <cmd> 3 days ago --joplin
+```
+
+### summary
+
+```sh
+uv run timesheets summary --joplin               # today, full detail
+uv run timesheets summary -w --joplin            # full week
+uv run timesheets summary -s --joplin            # short: one line per project
+uv run timesheets summary -w -s --joplin         # weekly short: per-day project totals
+uv run timesheets summary -w -ss --joplin        # weekly totals only: one line per day
+```
+
+### csv
+
+```sh
+uv run timesheets csv --joplin                   # stdout
+uv run timesheets csv --joplin -o output.csv     # write to file
+```
+
+### stories
+
+```sh
+uv run timesheets stories --joplin               # today
+uv run timesheets stories -w --joplin            # full week
+```
+
+### status
+
+```sh
+uv run timesheets status --joplin
+```
+
+## Config file
+
+Copy `timesheets.example.toml` to `timesheets.toml` in the working directory
+(or pass `--config /path/to/file.toml`):
+
+```toml
+[joplin]
+token = "your_api_token_here"
+
+[projects]
+map = "/path/to/project_map.json"
+
+[work]
+daily_hours = 8.0
+weekly_hours = 40.0
+```
+
+Priority order: **CLI flag > config file > environment variable > default**.
+
+## Joplin notebook structure
+
+```
+Work/
+└── Timesheets/
+    └── YYYY/
+        └── YYYY - WNN      ← note per week, one table per day
+```
+
+Each table is preceded by a heading of the form `# <weekday> - YYYY-MM-DD`.
+Open entries (start time present, end time absent) are used by the `status`
+command to calculate expected end time.