CLI: Centralize target specs and lint free-text examples in fullDescription #1649

Follow-up from review on #1575.

Problem

Many command fullDescription strings still carry free-text usage blocks such as Target patterns:, Pagination: and Filtering and output:. Each line is a hand-aligned sentry … # comment example. On main, 21 files under packages/cli/src/commands/ have one of those section labels, and about 170 such lines are spread across ~40 command files (for example project/list.ts, team/list.ts, repo/list.ts, monitor/list.ts, integration/list.ts, issue/list.ts, log/list.ts, span/list.ts, release/list.ts).

The target syntax (<org>/, <org>/<project>, <project>, auto-detect) is restated by hand per command. Only some commands use the shared targetPatternExplanation() helper in src/lib/list-command.ts, so the wording drifts between commands.

The no-examples-in-full-description rule in packages/cli/lint-rules/cli-oxlint-plugin.js only catches an Examples heading or Examples: label (EXAMPLES_LABEL_RE). These blocks get past it because they use other labels.

Proposal

1. Centralize target specs. Describe the accepted target forms once, from the positional definition (LIST_TARGET_POSITIONAL, LIST_ORG_TARGET_POSITIONAL and friends) or a shared helper. Then render them the same way in --help, the generated docs and the skill references. Drop the per-command Target patterns: blocks.
2. Move the remaining examples into docs.examples. Pagination, filtering and output examples belong in command metadata, like docs(cli): Move remaining fragment examples into command metadata #1633 did for the fragments.
3. Extend the lint rule. Make no-examples-in-full-description also flag example-like lines in fullDescription: indented lines starting with sentry (optionally with a trailing # comment), whatever label sits above them. That keeps new free-text examples from coming back.

Done when

• No command fullDescription contains indented sentry … example lines.
• Target syntax text comes from one shared source.
• The lint rule fails on a reintroduced free-text example block.

via Junior system actor event.

--

View Junior Session [Sentry]