Rework help and usage output: grouped layout, compact help, theme-safe color, usage chart (AGI-1169, AGI-1174)

AGENTS.md

@@ -55,7 +55,9 @@ easy thing to add:
 Everything about how output looks lives in `src/output/`: `mod.rs` is the
 entry point (modes, `emit`, tips), `error.rs` shapes and prints failures,
 `render.rs` builds tables and field lists, `style.rs` decides when color is
-allowed, and `banner.rs` is the version line a run opens with.
+allowed, `theme.rs` is the palette — every color the CLI uses, each held to
+a contrast rule by a test — and `banner.rs` is the version line a run opens
+with.
 
 Four modules may touch stdout, and the guard lists each with its reason:
 `output/mod.rs`, which is the machinery; `completion.rs`, because a shell
@@ -113,6 +115,12 @@ saying what to do. **If a guard fails, the fix is almost never to add
 yourself to its list** — read the reason first. When it genuinely is, add the
 entry *and* the sentence explaining it.
 
+One table outside that file works the same way: `GROUPS` in
+`src/help_layout.rs` places every command in a top-level help group, and
+`every_command_has_a_place` fails when a new command has no place there or
+an entry outlives its command. A command it misses still shows, under
+"Other", but CI will not let that ship.
+
 ## What the tests can and cannot tell you
 
 `cargo test` answers to fake tokens and a fake server. It runs offline, on a

CHANGELOG.md

@@ -19,6 +19,56 @@ that may never merge. They are not releases and are not listed here.
 
 ## Unreleased
 
+- `mapbox usage` reads as a chart: one row per product with no blank
+  lines between, every sparkline as wide as the period, bars scaled from
+  zero so their height is proportional to the value, and the tallest
+  stopping short of the row above. Each row is to its own scale and ends
+  with the peak its tallest bar stands for (`peak 407/day`). A day with any
+  usage never draws as a day without.
+  At a terminal the title and bars are in the accent over a muted
+  baseline, and the tips look like every other command's. The footer is
+  one line (`31 active days · generated 2026-09-08 09:49 UTC`), and the
+  `TOTAL` column lines up under its header. Text output only.
+
+- An API parameter's help line no longer stops at the first dot inside an
+  id, a number or "e.g.": `tilesets get-tile` described `<tilesets>` as
+  "Tileset ID(s) in the format `username" and now shows the whole first
+  sentence. Help text only; `--schema` always had the full description.
+
+- Color reads on light and dark terminal themes alike. Tables, tips, the
+  banner and help use a small fixed palette (teal, gray, red) instead of
+  the terminal's own bright blue and dim, which fell below 2:1 on some
+  light themes; every colored run of text is bold. Help asks the terminal
+  for its background and uses a palette made for a dark or a light one;
+  everything else, and help where the terminal doesn't answer, uses one
+  that reads on both. A terminal not known to show 24-bit color gets bold
+  and plain text instead. New `--no-color` flag turns color off, as
+  `NO_COLOR` does, and `FORCE_COLOR=1` now keeps color in a pipe; either
+  way off wins.
+
+- Top-level `mapbox --help` lists commands in groups (Maps and data,
+  Search, Account, Coding agents, CLI), each with a line saying what it
+  does rather than which API it wraps, and the global options under
+  Authentication, Output and Behavior, wrapped to the terminal. At a
+  terminal, help — top-level or a command's — opens with the
+  `mapbox · v<version>` banner, as a command run does.
+  Subcommand help uses clap's compact layout for `--help` as well as
+  `-h`, with the command's full description at the top, and points to
+  `mapbox --help` for the global options instead of repeating them; they
+  still work on every command. Headings are teal; names to type and values
+  to fill in are bold in the terminal's own foreground; notes are gray. clap's yellow and green in usage errors
+  are bold now too.
+  Help text only: no command, flag, exit code or result output changes.
+
+- Top-level `mapbox --help` / `mapbox help` changes. It ends with a
+  "Learn more" section linking the CLI docs, the agent-setup prompt,
+  Mapbox Agent Skills, the Mapbox MCP server and the API docs. When a
+  coding agent runs it (detected the same way as for the `User-Agent`),
+  it opens with a two-line hint pointing at `mapbox --schema`. Help also
+  wraps to the terminal width (100 columns when piped), and env-backed
+  options read `[env: NAME]` without the variable's value. Help text
+  only: no flag, exit code or result output changes.
+
 - **Breaking**: `--eta-type`, `--navigation-profile` and `--origin` removed
   from `mapbox search category`. The category endpoint does not currently
   return an ETA, so the flags were accepted but had no effect. A script

CONTRIBUTING.md

@@ -76,6 +76,11 @@ where the specs are maintained, which is inside Mapbox.
 editable: hand-authored specs for APIs Mapbox publishes no description for.
 See its own README.
 
+A new command, generated or hand-written, also needs a place in top-level
+`mapbox --help`: add it to `GROUPS` in `src/help_layout.rs`, and give an API
+command a one-line description in `DESCRIPTIONS` there, since its own is the
+spec's title. `every_command_has_a_place` fails until it has both.
+
 `build.rs` records which upstream commit the vendored specs came from, when
 that information is available to it. It is best-effort and can never fail a
 build — read its header before changing it.

Cargo.toml

@@ -59,7 +59,11 @@ todo = "deny"
 unimplemented = "deny"
 
 [dependencies]
-clap = { version = "4", features = ["derive", "env", "string"] }
+clap = { version = "4", features = ["derive", "env", "string", "wrap_help"] }
+# Already in the graph through clap's `wrap_help`. Used directly by the
+# top-level help, which src/help_layout.rs renders itself and so has to wrap
+# to the terminal itself.
+terminal_size = "0.4"
 # Renders `mapbox completion <shell>` from the same `Command` tree everything
 # else here is built from. Kept to the default features on purpose: the
 # dynamic-completion half is `unstable-dynamic`, and value completion is out
@@ -99,6 +103,13 @@ dirs = "5"
 # are needed for `parse_to_serde_value`, which decodes straight into a
 # `serde_json::Value`.
 jsonc-parser = { version = "0.34.0", features = ["serde", "serde_json"] }
+# Asks the terminal for its background color (OSC 11), so help can use the
+# palette for a dark or a light one. It reads the answer off the terminal,
+# which takes raw mode and a timed read — `unsafe` this crate does not
+# have — and it sends a second query every terminal answers, so one without
+# OSC 11 is known at once instead of after the timeout. Asked only by a run
+# that shows help; see src/output/theme.rs.
+terminal-colorsaurus = "1"
 
 [dev-dependencies]
 # Integration tests build fake Mapbox tokens; same crate the CLI already uses.

README.md

@@ -468,10 +468,15 @@ one flat object: `code`, `message`, plus `fix`, `next_actions` and `docs`
 where there is advice to give. See [docs/commands.md](./docs/commands.md#errors)
 for the list of codes.
 
-At a terminal, a run opens with a `mapbox · v<version>` line on stderr, and
-tables, labels and tips are in color. Neither reaches a pipe or a file.
-`-q`/`--quiet` (or `MAPBOX_QUIET=1`) hides the banner; `NO_COLOR` turns
-color off.
+At a terminal, a run — and any `--help` — opens with a
+`mapbox · v<version>` line on stderr, and help, tables, labels and tips
+are in color. Neither reaches a pipe or a file. `-q`/`--quiet` (or
+`MAPBOX_QUIET=1`) hides the banner. `--no-color` or `NO_COLOR` turns color
+off; `FORCE_COLOR=1` keeps it on into a pipe, for a pager such as
+`less -R`, and `--no-color`/`NO_COLOR` win over it. The colors are fixed
+and chosen to read on light and dark themes alike; help asks the terminal
+for its background to pick a palette for it. A terminal not known to show
+24-bit color gets bold text instead.
 
 ### `--schema`
 

docs/commands.md

@@ -538,6 +538,7 @@ either.
 | `--output`, `-o` | `auto` \| `text` \| `json`. |
 | `--id <value>` | On a command that returns a list, print just the row with that `id` or `name`. |
 | `--quiet`, `-q` | Don't print the `mapbox · v<version>` banner, which goes to stderr and only when stderr is a terminal. Also `MAPBOX_QUIET`. |
+| `--no-color` | Turn off color in help, errors and text output. Same as `NO_COLOR`; wins over `FORCE_COLOR`. |
 | `--timeout <seconds>` | How long one request may take, connection included. Defaults to 60 seconds, or 900 for a body read from `--file` or from a `--data @<path>`/`@-`. Also `MAPBOX_TIMEOUT`. |
 
 An operation with a request body takes `--data`/`-d` when that body is text
@@ -4179,15 +4180,11 @@ every line `-o text` prints around the table, is exactly what came back.
 Usage · 2026-08-09 → 2026-09-08
 
 PRODUCT                TOTAL  DAILY TREND
-Directions API    67,840,000  ▁▄▇▆▆▅▅▇▇▇▇▆▅▅▄▇▇██▇▇▆▅▅▇▇██▇▇▆
+Directions API    67,840,000  ▄▅▇▆▆▆▆▇▇▇▇▆▆▆▅▇▇▇▇▇▇▆▆▆▇▇▇▇▇▇▆  peak 2,618,385/day
+Matrix API        45,260,000  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇  peak 1,460,000/day
+Vector Tiles API       6,300  ▁▁▁▁▁▁▇▁▁▁▁▁▁▄▁▁▁▄▁▁▄▁▁▁▁▁▁▁▁▁▁  peak 3,300/day
 
-Matrix API        45,260,000  ▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅
-
-Vector Tiles API       6,300  ▆▁▆▁▁▁█▁▁▁▁▁▁█▁▁▁█▆▁█▄▁▁▁▁▄▁▁▁▁
-
-Active days: 31
-
-Generated 2026-09-08T09:49:10.827Z
+31 active days · generated 2026-09-08 09:49 UTC
 
 Tips:
   `-o json` for the exact per-day numbers and the per-browser/country/host breakdown.
@@ -4227,10 +4224,17 @@ JSON `-o json` prints. Each row is a product's total for the period plus a
 sparkline of its daily values — a padded one: a day the API's `daily` array
 leaves out (it omits a day rather than sending `usage: 0` for it) still gets
 its own zero-height glyph at the right position in the line, computed from
-`data.period`'s own start and end. Rows have a blank line between them —
-without it, a sparkline's solid glyphs sitting flush against the next
-row's read as cramped rather than dense, on an account with more than a
-couple of products. Exact per-day numbers and the per-browser/country/host
+`data.period`'s own start and end, so every product's line is the same
+width. Bars scale from zero to the product's own busiest day, the way
+ratatui's sparkline scales, so a bar's height is proportional to its value
+and a product used the same amount every day is at the top every day
+(`Matrix API` above). Since every row is to its own scale, each line ends
+with `peak N/day`, the day's usage its tallest bar stands for. A day with any
+usage is never drawn as the zero glyph.
+Rows stack one per line, and the tallest bar stops at `▇` rather than `█`,
+which leaves a gap under the row above so the products don't run
+together. At a terminal the bars are in the accent color over a muted
+baseline. Exact per-day numbers and the per-browser/country/host
 breakdown are left to `-o json`; `--product` narrows the whole response,
 both columns, to one product's row. A 403 covers two different causes the
 API doesn't otherwise distinguish: the token missing `statistics:read` — a
@@ -4259,9 +4263,7 @@ Directions API — total 67,840,000
   2026-08-10  2,150,000
   2026-08-09  2,100,000
 
-Active days: 31
-
-Generated 2026-09-08T09:49:10.827Z
+31 active days · generated 2026-09-08 09:49 UTC
 
 Tips:
   `-o json` for the per-browser/country/host breakdown.