Distillation

Date: Sep 10, 2026

• 🔴 (11:37) User stated command hints live exclusively on the CommandReturn return value, never on individual yields, in /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/lib/command.ts.
• 🔴 (11:37) User stated hidden injected global logging flags are always stripped so the command never sees them; ALWAYS_STRIP = new Set([LOG_LEVEL_KEY]).
• 🔴 (11:37) User stated all command functions are async generators: non-streaming commands yield one CommandOutput<T> and may return { hint }; streaming commands render each yield immediately, but --json commands must yield one aggregate value when callers need one parseable JSON document because individual JSON chunks are pretty-printed rather than JSONL; void commands may return without yielding for early exits such as --web.
• 🔴 (11:37) User’s /home/byk/Code/getsentry/cli-pr-1558/packages/cli/src/lib/command.ts defines CommandExample with readonly description and complete command fields, and extends native Stricli docs as CommandDocumentation with optional readonly examples.
• 🔴 (11:37) User’s command documentation convention treats customUsage[0] as the canonical signature suffix; later customUsage lines may document equivalent forms.
• 🔴 (11:37) User’s prepareNativeDocs() renders each example as ${command} # ${description} under an Examples: section, while attachDocumentationMetadata() stores canonical usage as __primaryUsage and examples as __examples.
• 🔴 (11:37) User’s enrichDocsWithSchema() appends JSON field names and types to fullDescription when outputConfig.schema produces at least one field; command-owned examples are prepared before schema enrichment so JSON fields remain at the end of native help.
• 🔴 (11:37) User’s GLOBAL_FLAG_DEFAULTS contains [LOG_LEVEL_KEY]: LOG_LEVEL_FLAG, verbose: VERBOSE_FLAG, org: ORG_FLAG, and project: PROJECT_FLAG.
• 🔴 (11:37) User’s mergeGlobalFlags() preserves command-owned global flags, injects missing defaults, and adds injected keys to stripKeys; it separately records commandOwnsOrg and commandOwnsProject. When an output config exists, it injects json: JSON_FLAG only if the command does not own json, and always sets fields = buildFieldsFlag(outputConfig).
• 🔴 (11:37) User’s buildCommand() derives global short aliases from GLOBAL_FLAGS; an alias is injected only when the command does not define the corresponding flag and the short alias is not already present.
• 🔴 (11:37) User stated all CLI commands must import buildCommand from the local command module rather than directly from @stricli/core, because direct Stricli imports bypass telemetry and global flag handling.