Add opt-in server sync

README.md

@@ -27,6 +27,7 @@ Works on **Arch Linux + Wayland** and is designed to be portable to other projec
 | `log_commit.py` | Called by git hook; do not run directly usually |
 | `zed_tracker.py` | Background tracker for Zed activity |
 | `generate_report.py` | Generate a markdown hours report |
+| `sync.py` | Opt-in incremental sync of local logs to a Zed Hours server |
 | `README.md` | This file |
 
 ---
@@ -124,6 +125,34 @@ python3 tools/time_tracking/generate_report.py --today
 
 ---
 
+## Optional server sync
+
+The tracker remains local-first. To opt in to sending the locally recorded heartbeats and commits to a compatible server, set these environment variables:
+
+```bash
+export ZED_HOURS_SERVER_URL="https://hours.example.com"
+export ZED_HOURS_SERVER_TOKEN="your-bearer-token"
+export ZED_HOURS_DEVICE_ID="laptop-1"
+```
+
+Then run from the tracked project root:
+
+```bash
+python3 tools/time_tracking/sync.py
+```
+
+The command posts heartbeats to `/api/v1/sync/zed-heartbeats` and commits to `/api/v1/sync/zed-commits`. It sends `device_id`, `project_slug`, and records in batches. The slug defaults to the project root directory name and can be overridden without exposing the absolute local project path:
+
+```bash
+python3 tools/time_tracking/sync.py \
+  --project-root /path/to/project \
+  --project-slug customer-portal
+```
+
+Progress is recorded locally in `.zed-hours/sync-state.json`. Retrying after a failed request is safe: each record has a deterministic, device-specific `source_id`, allowing the server to treat duplicate submissions as idempotent.
+
+---
+
 ## How activity detection works on Wayland
 
 Wayland does not expose a global active-window API for security reasons. The tracker tries several methods, in order:
@@ -180,6 +209,6 @@ The scripts detect the project root automatically from the current working direc
 ## Notes
 
 - This tool is intentionally simple and local. It is not a replacement for a commercial time tracker, but it is a reliable fallback when you forget to log hours.
-- The tracker does not send data anywhere.
+- The tracker does not send data anywhere unless you explicitly run `sync.py` with `ZED_HOURS_SERVER_URL`, `ZED_HOURS_SERVER_TOKEN`, and `ZED_HOURS_DEVICE_ID` configured.
 - Heartbeat granularity is one minute by default. Tune it in `config.json`.
 - Because of Wayland security, window detection may not give the exact filename. The filesystem fallback compensates for this.