Skip to content

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

Merged
DTTerastar merged 2 commits into
mainfrom
docs/getting-started-and-worked-examples
May 19, 2026
Merged

docs: Getting Started + three worked examples (crono / liftoff / withings)#24
DTTerastar merged 2 commits into
mainfrom
docs/getting-started-and-worked-examples

Conversation

@Terastar-Paperclip
Copy link
Copy Markdown
Contributor

Summary

  • GETTING_STARTED.md — zero-to-first-export guide; covers install (Homebrew + build-from-source), prime, auth per CLI, date flags, --format, and how to run the conformance suite. Links to CONTRACT.md and compat/README.md.
  • docs/example-crono.md — crono-export worked example: credentials, prime output, nutrition export, food-log jq recipe, biometrics query, flag-validation demonstration, compat suite run.
  • docs/example-liftoff.md — liftoff-export worked example: OAuth login, prime output, workouts list, bodyweight trend, compat suite run (parse-level; data-path skipped pending CI credential provisioning).
  • docs/example-withings.md — withings-export worked example: OAuth login, prime output, activity/sleep/measurements exports, full compat suite run (stub server + fake token; all §4 cells machine-attested).

Verification

All commands executed at HEAD against locally built binaries:

go build -o /tmp/crono-export crono-export-cli
go build -o /tmp/liftoff-export liftoff-export-cli
go build -o /tmp/withings-export withings-export-cli
EXPORT_CLI_BIN=/tmp/crono-export go test -tags=compat ./...   # ok
LIFTOFF_EXPORT_BIN=/tmp/liftoff-export go test -tags=compat ./...  # ok
WITHINGS_EXPORT_BIN=/tmp/withings-export go test -tags=compat ./... # ok

CONTRACT.md citations are verbatim (grep-verified). No fabricated §X references.

Content lenses applied

  • Inverted pyramid: lede names audience + outcome in one sentence per page.
  • Worked-example primacy: commands before explanations.
  • Recognition over recall: exact env var names, flag values, and exit codes shown.
  • Progressive disclosure: GETTING_STARTED.md covers the 80% path; deep config in prime and CONTRACT.md.

Reviewer

Awaiting DT (board) approval click. Shared GH identity means self-approval is blocked.

- GETTING_STARTED.md: zero-to-first-export guide for all three CLIs;
  covers install, auth, date flags, output formats, and conformance
  verification. Links to CONTRACT.md and compat/README.md.
- docs/example-crono.md: crono-export worked example with verified
  --help, prime, auth status, and flag-validation output.
- docs/example-liftoff.md: liftoff-export worked example with verified
  --help, prime, auth status output, and compat suite instructions.
- docs/example-withings.md: withings-export worked example with
  verified --help, prime, auth status output, and full compat suite
  instructions (stub server, fake token, all §4 cells machine-attested).

All commands executed at HEAD (2026-05-19) against locally built
binaries. Data-path examples show expected output shape; live output
requires real credentials. CONTRACT.md citations are verbatim grep-
verified; no fabricated §X references.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
CI's markdown-lint check (markdownlint-cli2 v0.13.0) flagged literal
tabs from captured `go test` output inside fenced code blocks in the
three worked examples. Replace tabs with spaces; visual alignment is
preserved, content is unchanged.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
@DTTerastar DTTerastar merged commit e30ccd9 into main May 19, 2026
6 checks passed
@DTTerastar DTTerastar deleted the docs/getting-started-and-worked-examples branch May 19, 2026 11:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants