## Problem The command list in [`README.md`](README.md) (the "Core commands" section) is hand-maintained. Nothing generates it — the dependency runs the other way, with `cmd/gen-docs/docs.go` pulling README intro prose into the generated docs index and linking back to the README. As a result the list has drifted badly: **23 of 46 top-level commands are wrong or missing.** ### 13 commands are missing entirely `artifact-registry`, `attestation`, `dependency-firewall`, `orbit`, `packages`, `runner`, `runner-controller`, `search`, `security`, `skills`, `todo`, `whatsnew`, `work-items` ### 10 descriptions no longer match the command's `Short` | Command | README says | `Short` says | |---|---|---| | `duo` | Generate terminal commands from natural language. | Work with GitLab Duo. | | `auth` | Manage the authentication state of the CLI. | Manage authentication for glab. | | `config` | Set and get CLI settings. | Manage glab settings. | | `changelog` | Interact with the changelog API. | Generate changelogs from your project's commit history. | | `check-update` | Check for updates to the CLI. | Check for the latest glab version. | | `label` | Manage labels for your project. | Manage labels on remote. | | `stack` | Create, manage, and work with stacked diffs. | Create, manage, and work with stacked diffs. (EXPERIMENTAL) | | `api` | Make authenticated requests to the GitLab API. | Make an authenticated request to the GitLab API. | | `cluster` | Manage GitLab agents for Kubernetes and their clusters. | Manage GitLab Agents for Kubernetes and their clusters. | | `version` | Show version information for the CLI. | Show version information for glab. | The `duo` entry is the most actively misleading: it describes `glab duo ask`, which is now a hidden subcommand. Someone landing on the project's front page learns the wrong thing about what `glab duo` is for. ## Proposal Generate the list from the cobra command tree in `cmd/gen-docs/docs.go`. The generator already does this exact walk for the docs index (`rootSubcommandList`, `cmd/gen-docs/docs.go:380-388`): ```go func rootSubcommandList(cmd *cobra.Command) string { var subcommands strings.Builder for _, cmdC := range cmd.Commands() { if cmdC.Name() != "help" && cmdC.IsAvailableCommand() { fmt.Fprintf(&subcommands, "- [`glab %s`](%s/_index.md)\n", cmdC.Name(), cmdC.Name()) } } return subcommands.String() } ``` `IsAvailableCommand()` already excludes hidden and deprecated commands (so `glab duo ask` correctly stays out), and cobra returns `Commands()` alphabetically, matching the README's current order. The README variant is the same loop plus `Short`: ```go fmt.Fprintf(&b, "- [`glab %s`](docs/source/%s): %s\n", cmdC.Name(), cmdC.Name(), cmdC.Short) ``` Delimit the block with markers so the hand-written intro, installation, and GitLab Duo prose are untouched: ```markdown <!-- BEGIN GENERATED COMMAND LIST — run `make gen-docs` --> - [`glab alias`](docs/source/alias): Create, list and delete aliases. ... <!-- END GENERATED COMMAND LIST --> ``` Enforcement is nearly free: lefthook's `check-generated` job (`lefthook.yml:141-161`) already runs `make gen-docs` followed by a whole-tree `git diff --quiet`, so a stale README would fail the push today — but it would misreport as "Generated Go code is out of date". Add `README.md` next to `docs/` in the first check so the message is accurate. ## Decisions to make while implementing 1. **Some `Short` strings are worse than the README wording.** For example `label`: README "Manage labels for your project." versus `Short` "Manage labels on remote." Generating forces convergence, so these should be resolved by improving the `Short` text (a user-visible `--help` change) rather than accepting a regression in the README. Needs a per-command judgement call for the 10 rows above. 1. **`(EXPERIMENTAL)` / `(BETA)` suffixes will start appearing** (for example `stack`). This is already the case for `mcp` in the README today, so it is consistent — just confirm it is wanted on the front page for the rest. 1. **Keep the existing link form** `](docs/source/<name>)`, not `](docs/source/<name>/_index.md)`, to avoid churning 33 links past lychee (`lefthook.yml:188`). 1. **Verify vale and markdownlint pass** on the generated block; both run against `README.md` in pre-push (`lefthook.yml:164-186`). The `Short` strings already clear vale under `docs/source/`, so the risk is low. ## Scope Roughly 30 lines in `cmd/gen-docs/docs.go` plus the markers and the lefthook path, then the `Short` wording decisions. Found while reviewing !3672, which repositions `glab duo` and leaves the README entry describing the now-hidden `ask` subcommand. That MR fixes its own line by hand; this issue covers generating the list so it cannot drift again.