Skip to content

docs: trim prime to one screen - #33

Merged
DTTerastar merged 1 commit into
mainfrom
docs/prime-shorter
May 10, 2026
Merged

docs: trim prime to one screen#33
DTTerastar merged 1 commit into
mainfrom
docs/prime-shorter

Conversation

@DTTerastar

Copy link
Copy Markdown
Contributor

Summary

The withings prime as merged was 143 lines (three terminal screens), in direct violation of CONTRACT §6:

Prime is short. It is not a man page. If it grows past one terminal screen, something belongs in this contract instead.

This trims it to 47 lines.

What came out

  • Per-subcommand JSON key dumps (~35 lines). Replaced with a documented self-discovery line: ` --since 1d --format json`. An LLM agent can introspect the schema at runtime — it doesn't need a frozen copy in the primer.
  • OAuth setup prose (~15 lines). The redirectmeto trick stays because it's the one non-obvious bit users need from the primer. The rest belongs in `auth login --help`.
  • Two of the five examples. Kept the three with the highest signal-per-line.
  • Gotchas tightened from multi-line paragraphs to single-line bullets.

Test plan

  • `go build ./...` passes
  • `withings-export prime` is 47 lines (was 143)
  • All seven CONTRACT §6 sections still present (WHAT IT IS / I/O / AUTH / DATE FLAGS / SUBCOMMANDS / EXAMPLES / GOTCHAS)

Cross-repo

Same diet applied in parallel to crono and liftoff (their primes had the same problem at 123 and 131 lines respectively). Three matching PRs, separate per repo.

🤖 Generated with Claude Code

The prime as shipped was 143 lines — three terminal screens — exactly
the man-page bloat the shared contract calls out:

  "Prime is short. It is not a man page. If it grows past one terminal
   screen, something belongs in this contract instead."

What came out:
- Per-subcommand JSON key dumps (~35 lines): redundant with
  '<subcommand> --since 1d --format json', which is now the documented
  way to discover row schemas.
- OAuth setup prose (~15 lines): the redirectmeto trick stays because
  it's the one non-obvious bit; everything else belongs in
  'auth login --help'.
- Two of the five examples; multi-line gotchas tightened to bullets.

Result: 47 lines, fits on a single terminal screen. Same shape as
crono and liftoff after their parallel diet.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@DTTerastar
DTTerastar merged commit eee4e19 into main May 10, 2026
2 checks passed
@DTTerastar
DTTerastar deleted the docs/prime-shorter branch May 10, 2026 21:28
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.

1 participant