With the auto-generated CLI reference now live (#41 / #43), the limiting factor on its quality is the Cobra metadata in `cli/cmd/`. None of the 14 commands set `Example`, and most flag descriptions are terse one-liners.
Approach
For each command in `cli/cmd/`:
- Add `cmd.Example` with one realistic invocation (renders in both `--help` and the generated `.md`)
- Add `cmd.Long` only where the name isn't self-explanatory (e.g. `auth login` is a device flow; `install` supports project-local install)
- Tighten flag descriptions where they're vague (e.g. `--digest` should mention the `sha256:` form)
Out of scope: duplicating the prose from the hand-written `docs/site/content/cli/*.md` pages. The generated reference stays exhaustive-but-terse; hand-written pages stay primary for narrative.
Acceptance
- Every leaf command (install, publish, explore, explore show, auth login/status/logout, config init/set/get/list) has an `Example` block
- `Long` set on commands where the short name is ambiguous
- Flag descriptions audited for clarity
- Generated reference at https://skillsctl.dev/cli/reference/ shows the new examples after merge
With the auto-generated CLI reference now live (#41 / #43), the limiting factor on its quality is the Cobra metadata in `cli/cmd/`. None of the 14 commands set `Example`, and most flag descriptions are terse one-liners.
Approach
For each command in `cli/cmd/`:
Out of scope: duplicating the prose from the hand-written `docs/site/content/cli/*.md` pages. The generated reference stays exhaustive-but-terse; hand-written pages stay primary for narrative.
Acceptance