Skip to content

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

Open
zmofei wants to merge 24 commits into
mainfrom
AGI-1169-help-learn-more
Open

zmofei wants to merge 24 commits into
mainfrom
AGI-1169-help-learn-more

Conversation

@zmofei

@zmofei zmofei commented Oct 8, 2026 •

Copy link
Copy Markdown
Member

Makes mapbox --help, command help and mapbox usage easier to read. Replaces #84, #85, #86 and #87.

Help

  • Top-level help groups commands by task, aligns everything in one column, and ends with links to the docs, Agent Skills and the MCP server.
  • Command help uses a compact layout and no longer repeats the global options on every page.
  • Groups live in src/help_layout.rs; a test fails if a new command isn't in one.

Color

  • Fixed colors that read on both light and dark terminals, following Cloudflare's cf CLI. Help picks a light or dark palette from the terminal's background.
  • New --no-color flag and FORCE_COLOR support.

mapbox usage

  • One sparkline per product, all the same width, each ending with its busiest day (peak 2,618,385/day).

Before / After

Top-level: mapbox --help

Before After
image image
image image

Subcommand: mapbox tilesets query --help

Before After
image image

Testing

The test suite passes, with and without a coding agent detected. Help fits at 80 columns and all links work.

Not checked: Windows terminals beyond CI, and which terminals answer the background color query.

@zmofei zmofei changed the title Link Mapbox docs, agent setup, skills and MCP from top-level help (AGI-1169) Improve top-level help: Mapbox links, --schema hint for agents, wrapping (AGI-1169) Oct 8, 2026
@zmofei zmofei added the locationai-team-skills Opened via the location-ai PR creation skill label Oct 8, 2026
zmofei added 9 commits October 8, 2026 15:09
One fixed palette for help, tables, tips and the banner, every color at
the same mid luminance so it reads on light and dark themes, falling back
to bold where 24-bit color is not known to render.

AGI-1174
A fixed accent sits at mid luminance to read on light themes, which made
headings darker than the reader's text on dark ones and clashed with
their theme's hue.

AGI-1174
@zmofei zmofei changed the title Improve top-level help: Mapbox links, --schema hint for agents, wrapping (AGI-1169) Rework help: grouped layout, compact subcommand help, theme-safe color (AGI-1169, AGI-1174) Oct 8, 2026
zmofei added 5 commits October 8, 2026 15:56
The accent is only ever bold, so it needs 3:1 rather than 4:1; at 0.26
luminance it is the brightest blue of its hue still at 3:1 on every theme
measured. --no-color is read off argv before the parse, since help is
rendered during it.

AGI-1169 AGI-1174
Help asks the terminal for its background (OSC 11) and uses a palette for
a dark or a light one; other runs, and help where the terminal doesn't
answer, keep the palette that reads on both. Only help asks: the answer
is read off the terminal's input, and a command that prompts afterwards
lost the answer typed ahead. Every colored run of text is bold.

AGI-1169 AGI-1174
As cf --help does: help is the page read most, and the version is often
what the reader came for. stderr, at a terminal, and -q still hides it.

AGI-1174
One row per product, every sparkline the width of the period, bars scaled
from zero and capped at the seven-eighths block so rows don't run
together. Title, bars and tips use the palette; the footer is one line;
TOTAL lines up under its header.
@zmofei zmofei changed the title Rework help: grouped layout, compact subcommand help, theme-safe color (AGI-1169, AGI-1174) Rework help and usage output: grouped layout, compact help, theme-safe color (AGI-1169, AGI-1174) Oct 8, 2026
zmofei added 2 commits October 8, 2026 17:45
Tileset hosting at 1 a day with one day at 0 failed the every-day-equal
test and scaled every 1 to the top glyph.
Each product is to its own scale, so a series with one value is at its
busiest every day; the cap at the seven-eighths block already keeps it
off the row above.
zmofei added 2 commits October 8, 2026 17:51
Every row is to its own scale, so the tallest bar means a different number
on each; say which after the line, as Tufte labels a sparkline.
@zmofei
zmofei marked this pull request as ready for review October 8, 2026 14:59
@zmofei
zmofei requested a review from a team as a code owner October 8, 2026 14:59
@zmofei zmofei changed the title Rework help and usage output: grouped layout, compact help, theme-safe color (AGI-1169, AGI-1174) Rework help and usage output: grouped layout, compact help, theme-safe color, usage chart (AGI-1169, AGI-1174) Oct 8, 2026

@mattpodwysocki mattpodwysocki left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ran the real output, not just the diff: the grouping, column alignment, learn-more links (agent-setup/prompt.md included, that's a real 200 now that #199 is in), --no-color/NO_COLOR/FORCE_COLOR, and the usage sparklines all work as described. The Windows handling is the part I cared most about given the arm64 build work going on elsewhere right now, and it's solid: console_renders_ansi gates raw escapes to terminals that actually advertise VT support, the OSC 11 query is bounded to 100ms and only runs during --help, and it falls back to the mid-luminance palette rather than guessing. every_command_has_a_place genuinely catches an unassigned command too.

Two small corrections for the description, neither blocks anything:

  • "fits at 80 columns" isn't quite what's shipped, MAX_WIDTH is 100 (help_layout.rs:108, main.rs:439 caps clap the same way), and the real -o, --output line runs to 99 characters.
  • #86 isn't closed/superseded the way #84/#85/#87 are, it's merged, just into this branch rather than main. Content's all here either way, just worth saying "merged into this branch" rather than "replaces" for that one.

Approving.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

locationai-team-skills Opened via the location-ai PR creation skill

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants