Distillation

🔴 (09:57) User stated command hints live exclusively on the async generator return value (CommandReturn) and never on individual yields; non-streaming commands yield one CommandOutput<T>, streaming commands render each yield immediately, JSON-capable commands must yield one aggregate value when one parseable JSON document is required, and void commands may return without yielding.

🔴 (09:57) User’s changes in packages/cli/src/lib/command.ts introduce and export CommandExample with readonly description and command fields; command must be a complete command line including the sentry executable.

🔴 (09:57) User’s changes in packages/cli/src/lib/command.ts export CommandDocumentation, extending Stricli’s native docs with optional readonly examples?: readonly CommandExample[]; customUsage[0] remains the canonical signature suffix while later lines may document equivalent forms.

🔴 (09:57) User added prepareNativeDocs() in packages/cli/src/lib/command.ts: it strips structured examples before passing docs to Stricli and, when examples exist, appends a native-help section formatted as Examples: followed by lines of ${command} # ${description}. Examples are prepared before enrichDocsWithSchema() so JSON-field help remains at the end.

🔴 (09:57) User added attachDocumentationMetadata() in packages/cli/src/lib/command.ts: it retains the first customUsage entry as non-standard __primaryUsage and retains structured examples as __examples; buildCommand() now calls this helper after stricliCommand() rather than attaching only __primaryUsage inline.

🔴 (09:57) User’s packages/cli/src/lib/introspect.ts changes add Command.__examples?: readonly CommandExample[] and make buildCommandInfo() prefer structured command-owned examples over legacy documentation examples. Each structured example becomes # ${description}\n${command}; legacy examples remain the fallback when __examples is absent or empty.

🔴 (09:57) User’s getPositionalString() change in packages/cli/src/lib/introspect.ts renders optional tuple positionals as [<placeholder>] and required tuple positionals as <placeholder>; missing placeholders still fall back to arg${index}. Array positionals remain <placeholder...>.

🔴 (09:57) User’s packages/cli/script/generate-command-docs.ts change renders optional positional arguments in argument tables as `[<placeholder>]` instead of always using `<placeholder>`.

🔴 (09:57) User added exported formatCommandExamples(examples: readonly string[]) in packages/cli/script/generate-skill-markdown.ts. It returns an empty string for zero examples; otherwise it emits an **Examples:** section with a fenced bash block and examples separated by blank lines via examples.join("\n\n").

🔴 (09:57) User updated both packages/cli/script/generate-command-docs.ts and packages/cli/script/generate-skill.ts to use the shared formatCommandExamples() helper, eliminating duplicated example-section rendering logic.

🔴 (09:57) User changed the generated-doc model in packages/cli/script/generate-command-docs.ts: generated pages now combine (1) auto-generated reference and examples from CLI metadata or the environment registry and (2) hand-written guides and tips from docs/src/fragments/; fragments remain the committed source of truth only for content that cannot live in command definitions.

🔴 (09:57) User changed packages/cli/script/check-fragments.ts so subcommands with cmd.examples.length > 0 are skipped when checking whether a hand-written fragment covers every subcommand; fragment coverage remains required for commands without command-owned examples.

🔴 (09:57) User updated packages/cli/src/lib/list-command.ts: buildListCommand() now accepts docs: CommandDocumentation, and OrgListCommandDocs is now an alias of CommandDocumentation, allowing list-command builders to carry structured examples and native Stricli documentation fields.

🔴 (09:57) User updated packages/cli/src/lib/mutate-command.ts so buildDeleteCommand() accepts docs: CommandDocumentation, allowing delete-command builders to carry the same structured documentation metadata.

🔴 (09:57) User added a test in packages/cli/test/commands/agent-conversation/list.test.ts asserting that organization-resolution errors use the canonical optional-organization command signature sentry agent-conversation list [<org>] when resolveOrgSpy returns null.

🔴 (09:57) User added a test in packages/cli/test/lib/command.test.ts asserting that buildCommand() retains structured example metadata in __examples; the fixture example is description Select an organization explicitly with command sentry thing list my-org.

🔴 (09:57) User expanded the property test in packages/cli/test/lib/introspect.property.test.ts to generate both placeholder and optional for tuple positionals and assert exact inclusion of either [<${placeholder}>] or <${placeholder}>; the property still runs with DEFAULT_NUM_RUNS.

🔴 (09:57) User added a unit test in packages/cli/test/lib/introspect.test.ts asserting that tuple positionals { placeholder: "required" } and { placeholder: "optional", optional: true } render exactly as <required> [<optional>].

🔴 (09:57) User added a buildCommandInfo() test in packages/cli/test/lib/introspect.test.ts proving structured __examples override a legacy example sentry thing list stale-org. The expected ordered results are: 1. # Use automatic organization detection\nsentry thing list; 2. # Select an organization explicitly\nsentry thing list my-org.

🔴 (09:57) A repository search found 26 matches for example-related test/documentation references, including packages/cli/test/lib/utils.test.ts, arg-parsing.test.ts, errors.test.ts, dsn.test.ts, issue-id.test.ts, command.test.ts, introspect.test.ts, and help.test.ts.

🔴 (09:57) A repository search found 9 matches for non-standard command metadata: __primaryUsage, __jsonSchema, and __rawFunc in packages/cli/src/lib/command.ts; __jsonSchema and __primaryUsage definitions/usages in packages/cli/src/lib/introspect.ts; and __primaryUsage consumption in packages/cli/src/lib/help.ts.

🔴 (09:58) A search in packages/cli/script/generate-skill.ts found 3 documentation-example loading references: loadCommandExamples() at line 488, passing docExamples to extractRouteGroupCommands() at line 496, and retrieving docExamples.get(path) ?? [] at line 500.

Distillation

Observations