Skip to content

Reorganize README, fix its command list, and check it against the binary - #63

Merged
zmofei merged 3 commits into
docs/readme-homebrewfrom
docs/readme-structure
Sep 29, 2026
Merged

zmofei merged 3 commits into
docs/readme-homebrewfrom
docs/readme-structure

Conversation

@zmofei

@zmofei zmofei commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

Stacked on #62. Merge that first.

Three commits:

1. Reorganize sections. The README now follows what a reader does: install, log in, run commands. Text is moved, not rewritten.

  • Uninstall moves under Install, and Auth becomes a top-level Authentication section.
  • Agent skills and Generate skills are grouped under For AI agents.
  • Usage is renamed Global options. Update notices, history and logs get their own section.
  • Privacy becomes top-level. every_telemetry_marker_is_disclosed now finds it by ## Privacy. I checked that it still fails when a disclosure is removed and when the section is missing.
  • Every heading other docs link to keeps its anchor.

2. Check README's commands against the binary. Two tests in tests/docs_contract.rs:

  • Every mapbox … in a shell block or inline code span must be a real command from mapbox --schema.
  • Every top-level command appears at least once.

Run against the README before commit 3, they report the four fake groups and the three missing commands below. They also catch a typo in a nested subcommand (styles draft gett).

3. Fix the command list and trim.

  • The API group list named rasterarrays, static-images, static-tiles and tilequery, which the binary doesn't have, and left out static. doctor, usage and config weren't mentioned; a new Diagnostics and settings section covers them.
  • Agent skills, completion, generate-skills and Tileset CLI are cut to examples plus a link, since docs/commands.md covers each fully. Implementation notes are gone, and the installer-test note moves to CONTRIBUTING.md.
  • Update notices, history, logs and Privacy are left as they were. docs/commands.md links to the README for the first three, and Privacy is legal text.

Not checked: the new tests cover command paths only, not flags or descriptions in README prose.

Unrelated, found along the way: REPO_URL in src/main.rs and repository in Cargo.toml point at github.com/mapbox/cli, which redirects to mapbox/cli-opensource-preview, not this repo. It shows up in help text such as mapbox usage --help. Left alone in case it's intentional.

@zmofei
zmofei requested a review from a team as a code owner September 29, 2026 09:12
The README listed four API groups (rasterarrays, static-images, static-tiles, tilequery) the binary no longer has, and never mentioned doctor, usage or the real static group. Nothing read the README, so nobody noticed.
@zmofei zmofei changed the title Reorganize README sections Reorganize README, fix its command list, and check it against the binary Sep 29, 2026
@zmofei
zmofei added this pull request to stack #65 September 29, 2026 09:35
@zmofei
zmofei merged commit 4201078 into main Sep 29, 2026
16 checks passed
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