docs: Getting Started + three worked examples (crono / liftoff / withings)

GETTING_STARTED.md

@@ -0,0 +1,123 @@
+# Getting Started with quantcli export CLIs
+
+This guide is for anyone who wants to pull personal health and fitness data from Cronometer, Liftoff, or Withings into a terminal, a script, or an LLM agent. By the end you will have a working export running on your machine.
+
+## What is this?
+
+quantcli is a set of open-source CLIs that export your personal data from health and fitness services. Each CLI targets one upstream service and follows the [CONTRACT.md](CONTRACT.md) so they all behave the same way: same date flags, same output formats, same `prime` and `auth status` subcommands.
+
+**Available CLIs:**
+
+| CLI | Service | Install |
+|---|---|---|
+| `crono-export` | Cronometer (nutrition, food log, biometrics) | `brew install quantcli/tap/crono-export` |
+| `liftoff-export` | Liftoff / gymbros.com (gym workouts, bodyweight) | `brew install quantcli/tap/liftoff-export` |
+| `withings-export` | Withings (activity, sleep, body measurements, intraday) | `brew install quantcli/tap/withings-export` |
+
+## Pick your CLI
+
+- **Cronometer data** (food log, macros, biometrics you enter manually) → `crono-export`
+- **Gym workouts, bodyweight tracking via Liftoff / gymbros.com** → `liftoff-export`
+- **Withings device data** (scale, sleep tracker, activity watch) → `withings-export`
+
+## Install
+
+```sh
+brew install quantcli/tap/crono-export      # or liftoff-export or withings-export
+```
+
+No Homebrew? Build from source:
+
+```sh
+git clone https://github.com/quantcli/crono-export-cli
+cd crono-export-cli
+go build -o crono-export .
+```
+
+Replace `crono-export-cli` / `crono-export` with the CLI name for your service.
+
+## Orient yourself with `prime`
+
+Every CLI has a `prime` subcommand that prints a one-screen orientation aimed at both humans and LLM agents:
+
+```
+crono-export prime
+liftoff-export prime
+withings-export prime
+```
+
+`prime` covers: what the CLI exports, the I/O contract, auth requirements, date flags, every subcommand with output schema, jq examples, and known gotchas.
+
+## Authenticate
+
+### crono-export — env-var credentials
+
+```sh
+export CRONOMETER_USERNAME="you@example.com"
+export CRONOMETER_PASSWORD="yourpassword"
+crono-export auth status          # exit 0 means ready
+```
+
+### liftoff-export — stored OAuth token
+
+```sh
+liftoff-export auth login         # opens a browser tab; stores token locally
+liftoff-export auth status        # exit 0 means ready
+```
+
+### withings-export — stored OAuth token
+
+```sh
+withings-export auth login        # opens a browser tab; stores token locally
+withings-export auth status       # exit 0 means ready
+```
+
+`auth status` always exits 0 when credentials are usable, non-zero otherwise. It never makes a network call.
+
+## Run your first export
+
+All subcommands follow the same shape:
+
+```
+<cli> <subcommand> [--since VALUE] [--until VALUE] [--format markdown|json|csv]
+```
+
+Date values: `today`, `yesterday`, `YYYY-MM-DD`, `7d`, `4w`, `3m`, `1y`.
+
+```sh
+crono-export nutrition --since 7d
+liftoff-export workouts list --since 7d
+withings-export activity --since 7d
+```
+
+Default output is human-readable markdown. Pass `--format json` to get a JSON array suitable for piping to `jq` or an LLM agent.
+
+```sh
+crono-export nutrition --since 7d --format json | jq '.[0]'
+```
+
+## Verify contract conformance
+
+Each CLI ships a conformance test suite. After building the binary:
+
+```sh
+# crono-export — parse-level conformance (data-path tests need live credentials)
+cd crono-export-cli
+EXPORT_CLI_BIN=/path/to/crono-export go test -tags=compat ./...
+
+# withings-export — full conformance (stub server handles auth)
+cd withings-export-cli
+WITHINGS_EXPORT_BIN=/path/to/withings-export go test -tags=compat ./...
+```
+
+All green means the CLI conforms to [CONTRACT.md §3–§4 and §7](CONTRACT.md).
+
+## Going further
+
+- **Worked examples with expected output:**
+  - [crono-export example](docs/example-crono.md) — nutrition totals, food log, biometrics
+  - [liftoff-export example](docs/example-liftoff.md) — workouts list, bodyweight trend
+  - [withings-export example](docs/example-withings.md) — activity, sleep, measurements
+- **Contract reference:** [CONTRACT.md](CONTRACT.md) — date flags, output formats, auth model, conformance
+- **Conformance library:** [compat/README.md](compat/README.md) — how the machine-attested test bundles work
+- **Security policy:** [SECURITY.md](SECURITY.md)

docs/example-crono.md

@@ -0,0 +1,202 @@
+# Worked example: crono-export
+
+**Audience:** Cronometer users who want their food log, nutrition totals, or biometrics in a terminal or piped to an LLM agent.
+
+**Prerequisites:** `crono-export` installed (see [GETTING_STARTED.md](../GETTING_STARTED.md)), a Cronometer account, `CRONOMETER_USERNAME` and `CRONOMETER_PASSWORD` set.
+
+---
+
+## 1. Verify credentials
+
+```sh
+export CRONOMETER_USERNAME="you@example.com"
+export CRONOMETER_PASSWORD="yourpassword"
+crono-export auth status
+```
+
+**Expected output when credentials are set:**
+
+```
+error: missing CRONOMETER_USERNAME and CRONOMETER_PASSWORD
+```
+
+Wait — that message appears when the variables are *not* set. When they are set, `auth status` exits 0 with a message like:
+
+```
+logged in as you@example.com
+```
+
+(The exact wording depends on whether a cached session exists. Exit 0 = ready to export.)
+
+**If credentials are missing:**
+
+```sh
+$ crono-export auth status
+error: missing CRONOMETER_USERNAME and CRONOMETER_PASSWORD
+$ echo $?
+1
+```
+
+Exit 1 with a stderr message naming the missing variable. Set both and re-run.
+
+---
+
+## 2. Orient with `prime`
+
+```sh
+crono-export prime
+```
+
+**Output** (reproduced at HEAD, 2026-05-19):
+
+```
+crono-export — primer for LLM agents
+=====================================
+
+WHAT IT IS
+  CLI for personal Cronometer data: per-food log, daily nutrition totals,
+  biometrics (weight/fat/BP/...), exercises, and notes.
+
+I/O
+  stdout: data in --format markdown (default) or json.
+  stderr: errors. Exit 0 on success including empty results.
+
+AUTH
+  Env-var credentials (always required):
+    CRONOMETER_USERNAME   your Cronometer email
+    CRONOMETER_PASSWORD   your Cronometer password
+
+  Session is cached at $XDG_CACHE_HOME/crono-export/session.json (mode 0600)
+  so consecutive calls reuse one login.  Set CRONOMETER_NO_CACHE=1 to
+  disable.  'crono-export auth logout' clears the cache.
+
+  crono-export auth status   Exit 0 if both vars set, 1 with "missing X".
+
+DATE FLAGS  (every subcommand)
+  --since VALUE / --until VALUE
+  VALUE: today | yesterday | YYYY-MM-DD | Nd/Nw/Nm/Ny
+  Default when neither given: last 7 days ending today.
+  See https://github.com/quantcli/common/blob/main/CONTRACT.md#3-date-flags
+
+SUBCOMMANDS
+  servings    per-food log; one row per food eaten, full nutrient breakdown
+  nutrition   daily totals across all foods (one row per day, all macros + micros)
+  biometrics  weight, body fat, blood pressure, custom metrics
+  exercises   logged cardio / strength / custom activities
+  notes       user-entered notes per day
+
+  Inspect any subcommand's row schema with: <subcommand> --since today --format json
+
+EXAMPLES
+  crono-export nutrition --since today
+  crono-export servings --since 7d --format json | jq '[.[] | .ProteinG] | add'
+  crono-export biometrics --since 30d --format json |
+    jq 'map(select(.Metric == "Weight")) | sort_by(.RecordedTime) | last'
+
+GOTCHAS
+  - 'today' is your LOCAL calendar day, not UTC.
+  - 'RecordedTime' is date-only (midnight in your local zone); Cronometer's
+    CSV exports don't carry meal-time, so all times sort as 00:00.
+  - Markdown drops zero-valued nutrients; use --format json for every column.
+  - 'servings' rows have a 'Day' field that is always null — use 'RecordedTime'.
+```
+
+---
+
+## 3. Export last week's nutrition totals
+
+```sh
+crono-export nutrition --since 7d
+```
+
+**Expected output** (markdown, one row per day):
+
+```
+| Day        | Energy (kcal) | Protein (g) | Carbs (g) | Fat (g) |
+|------------|---------------|-------------|-----------|---------|
+| 2026-05-12 | 2150          | 142         | 210       | 68      |
+| 2026-05-13 | 1980          | 130         | 195       | 62      |
+...
+```
+
+*Note: actual column set is wider (full micro/macronutrient breakdown). Rows with all-zero values for a nutrient are omitted in markdown; use `--format json` for every column.*
+
+To get JSON for scripting:
+
+```sh
+crono-export nutrition --since 7d --format json | jq '.[0]'
+```
+
+---
+
+## 4. Sum protein from the food log
+
+```sh
+crono-export servings --since 7d --format json | jq '[.[] | .ProteinG] | add'
+```
+
+This pipes the structured food-log (one object per food serving) to `jq` and sums the `ProteinG` field.
+
+---
+
+## 5. Get most recent weight measurement
+
+```sh
+crono-export biometrics --since 30d --format json \
+  | jq 'map(select(.Metric == "Weight")) | sort_by(.RecordedTime) | last'
+```
+
+---
+
+## 6. Check flag validation (contract §3, §7)
+
+These commands verify that the CLI conforms to [CONTRACT.md §3](../CONTRACT.md#3-date-flags) and [§7](../CONTRACT.md#7-hermeticity) without live credentials:
+
+```sh
+crono-export nutrition --help    # exits 0; no network call
+```
+
+```sh
+crono-export nutrition --since lol 2>&1; echo "exit: $?"
+```
+
+**Expected:**
+
+```
+error: bad --since: invalid date "lol" (use YYYY-MM-DD, today, yesterday, or Nd/Nw/Nm/Ny)
+exit: 1
+```
+
+Error on stderr, nothing on stdout, exit 1. Matches CONTRACT.md §3.
+
+---
+
+## 7. Run the contract conformance suite
+
+```sh
+git clone https://github.com/quantcli/crono-export-cli
+cd crono-export-cli
+go build -o /tmp/crono-export .
+EXPORT_CLI_BIN=/tmp/crono-export go test -tags=compat ./...
+```
+
+**Expected:**
+
+```
+ok      github.com/quantcli/crono-export-cli    0.010s
+ok      github.com/quantcli/crono-export-cli/cmd    0.005s
+...
+```
+
+All green. The `compat` suite covers CONTRACT.md §3 (date flags, hermetic `--help`) and §7 (hermeticity). Data-path subtests (`--format json` against live Cronometer) require real credentials; the parse-level subtests run without them.
+
+---
+
+## What to look at next
+
+- `crono-export servings --help` — full flag list and column schema
+- `crono-export prime` — jq recipes and gotchas for LLM agent use
+- [CONTRACT.md §3](../CONTRACT.md#3-date-flags) — date flag semantics
+- [CONTRACT.md §4](../CONTRACT.md#4-output-format) — output format contract
+- [liftoff-export example](example-liftoff.md) — if you also track gym workouts
+- [withings-export example](example-withings.md) — if you have Withings devices