From 8d6dc764b3deced91417f7c84441969fa1248449 Mon Sep 17 00:00:00 2001 From: DTTerastar Date: Sat, 25 Apr 2026 20:53:50 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20trim=20prime=20to=20one=20screen,=20per?= =?UTF-8?q?=20CONTRACT=20=C2=A76?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The prime as shipped was 123 lines — over two 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 (~25 lines): redundant with ' --since today --format json', now the documented way to discover row schemas. - OUTPUT FORMATS prose tightened to two lines. - Two of the six examples; multi-line gotchas tightened to bullets. Result: 46 lines, fits on a single terminal screen. Co-Authored-By: Claude Opus 4.7 (1M context) --- cmd/prime.go | 111 +++++++++++++-------------------------------------- 1 file changed, 28 insertions(+), 83 deletions(-) diff --git a/cmd/prime.go b/cmd/prime.go index 6185082..502358c 100644 --- a/cmd/prime.go +++ b/cmd/prime.go @@ -10,113 +10,58 @@ const primeText = `crono-export — primer for LLM agents ===================================== WHAT IT IS - A CLI that reads your personal Cronometer data (per-food log, daily totals, - weight/biometrics, exercises, notes) and prints it on stdout. + CLI for personal Cronometer data: per-food log, daily nutrition totals, + biometrics (weight/fat/BP/...), exercises, and notes. -OUTPUT FORMATS - Default: narrow, fitdown-style markdown — date-grouped headings, one - bullet per non-zero field, easy to skim and easy for an LLM to consume - inline. Zero-valued nutrients are suppressed in markdown. - - --format json Pretty-printed JSON ARRAY of full rows. Use this when - you want the complete row, when piping to jq, or when - round-tripping into other tools. Nothing is suppressed. - - Errors go to stderr. You do NOT need '2>&1'. Exit code is 0 on - success and non-zero on auth or network failure. An empty result is - success — markdown prints "_(no records in window)_", JSON prints '[]'. +I/O + stdout: data in --format markdown (default) or json. + stderr: errors. Exit 0 on success including empty results. AUTH - Set both env vars before invoking. No config file or token cache; the CLI - logs in on every run. + Env-var only — the CLI logs in on every run, no token cache. CRONOMETER_USERNAME your Cronometer email CRONOMETER_PASSWORD your Cronometer password - 'crono-export auth status' is a fast local check that exits 0 when both - vars are set, 1 with a clear "missing X" message otherwise. + crono-export auth status Exit 0 if both vars set, 1 with "missing X". -DATE FLAGS (every export subcommand accepts these) - --since VALUE inclusive lower bound - --until VALUE inclusive upper bound; defaults to today +DATE FLAGS (every subcommand) + --since VALUE / --until VALUE VALUE: today | yesterday | YYYY-MM-DD | Nd/Nw/Nm/Ny - (no flag) last 7 days, ending today - + Default when neither given: last 7 days ending today. See https://github.com/quantcli/common/blob/main/CONTRACT.md#3-date-flags - for the cross-CLI specification. SUBCOMMANDS + servings per-food log; one row per food eaten, full nutrient breakdown + nutrition daily totals across all foods (string-valued JSON — see GOTCHAS) + biometrics weight, body fat, blood pressure, custom metrics + exercises logged cardio / strength / custom activities + notes user-entered notes per day - servings — per-food log: one row per food eaten, full nutrient breakdown. - Markdown: ## per date, ### per food (group · name · quantity), bullets - for non-zero nutrients. - JSON: typed numbers. Keys (subset): - RecordedTime, Group, FoodName, QuantityValue, QuantityUnits, - EnergyKcal, ProteinG, CarbsG, FiberG, FatG, SodiumMg, CalciumMg, - IronMg, B12Mg, VitaminDUI, Omega3G, ... (60+ nutrients). - - nutrition — daily totals: one row per day across all foods logged that day. - Markdown: ## per date, bullets for non-zero columns. - JSON: string-keyed (raw CSV columns, ALL VALUES ARE STRINGS — cast in jq). - Keys (subset): - "Date", "Energy (kcal)", "Protein (g)", "Carbs (g)", "Fat (g)", - "Fiber (g)", "Sodium (mg)", "Iron (mg)", "Calcium (mg)", - "B12 (Cobalamin) (µg)", "Cholesterol (mg)", "Completed", ... - - biometrics — weight, body fat, blood pressure, custom metrics. - Markdown: ## per date, bullet per metric: "- Metric: amount unit". - JSON keys: RecordedTime, Metric, Unit, Amount. - - exercises — logged cardio / strength / custom activities. - Markdown: ## per date, one bullet per session. - JSON keys: RecordedTime, Exercise, Minutes, CaloriesBurned, Group. - - notes — user-entered notes per day. Markdown: ## per date with note - body. JSON: string-keyed (raw CSV). + Inspect any subcommand's row schema with: --since today --format json EXAMPLES - - # Today's macros, scannable crono-export nutrition --since today - - # Today's macros, parsed (numbers via tonumber) - crono-export nutrition --since today --format json | jq '.[] | { - date: .Date, - kcal: (."Energy (kcal)" | tonumber), - protein: (."Protein (g)" | tonumber) - }' - - # 7-day protein total (servings is typed — no tonumber needed) crono-export servings --since 7d --format json | jq '[.[] | .ProteinG] | add' - - # All foods from today's breakfast - crono-export servings --since today --format json | jq '[.[] | select(.Group == "Breakfast") | .FoodName]' - - # All servings on a specific day - crono-export servings --since 7d --format json | jq '[.[] | select(.RecordedTime | startswith("2026-04-25"))]' - - # Latest weight reading in a 30-day window - crono-export biometrics --since 30d --format json | jq 'map(select(.Metric == "Weight")) | sort_by(.RecordedTime) | last' + 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. + - 'today' is your LOCAL calendar day, not UTC. - 'nutrition' and 'notes' JSON values are STRINGS (raw CSV) — cast with - 'jq tonumber' when doing math. 'servings', 'biometrics', 'exercises' - JSON values are already typed numbers. - - Markdown drops zero-valued nutrients to stay readable. If you need - every column (including zeros), use --format json. - - Cronometer logs by calendar day; nothing here is real-time. Two - '--since today' calls moments apart return the same data. - - 'servings' JSON rows contain a 'Day' field that is always null — use - 'RecordedTime' (an ISO-8601 timestamp) for any date-based filtering. + 'jq tonumber' when doing math. 'servings', 'biometrics', 'exercises' + are typed numbers. + - Markdown drops zero-valued nutrients; use --format json for every column. + - 'servings' rows have a 'Day' field that is always null — use 'RecordedTime'. ` var primeCmd = &cobra.Command{ Use: "prime", - Short: "Print an LLM-targeted primer (output formats, subcommands, jq recipes)", + Short: "Print an LLM-targeted primer (one screen)", Long: `Print a one-screen primer aimed at LLM agents calling this CLI as a tool. -Covers the output formats (markdown by default, --format json for structured), -auth env vars, the subcommands and what their rows look like, the shared -date flags, and a few jq recipes for common questions.`, +Covers I/O, auth, the shared date flags, the subcommand menu, and a few jq +recipes. Per the quantcli contract, prime is short — anything that wants +to grow into a man page belongs in --help on the relevant subcommand or +in https://github.com/quantcli/common/blob/main/CONTRACT.md.`, RunE: func(cmd *cobra.Command, _ []string) error { _, err := fmt.Fprint(cmd.OutOrStdout(), primeText) return err