Distillation

Date: Sep 9, 2026

• 🔴 (16:18) User stated command hints live exclusively on the CommandReturn return value, never on individual yields.
• 🟡 (16:18) Tool diff showed packages/cli/src/lib/command.ts adding exported CommandExample with readonly description and command strings; CommandDocumentation now extends native Stricli docs with optional readonly examples?: readonly CommandExample[].
• 🟡 (16:18) Tool diff documented the SentryCommandFunction contract: all command functions are async generators; non-streaming commands yield one CommandOutput<T> and may return { hint }; streaming yields render immediately; --json commands must yield one aggregate value when one parseable JSON document is needed because individual chunks are pretty-printed rather than JSONL; void commands return without yielding for early exits such as --web.
• 🟡 (16:18) Tool diff showed buildFieldsFlag() returning the base FIELDS_FLAG when no output schema or no extracted schema fields exist; otherwise it appends available field names from extractSchemaFields() to the flag brief as . Available: ${fieldNames}.
• 🟡 (16:18) Tool diff showed enrichDocsWithSchema() appending formatSchemaForHelp(schemaFields) to fullDescription, using docs.fullDescription ?? docs.brief as the base, only when the output configuration has a schema with at least one extracted field.
• 🟡 (16:18) Tool diff showed yielded-output handling in buildCommand(): a ClearScreen token sets deferred pendingClear only outside plain and JSON modes; other values render only when an output configuration and renderer exist and the value is a CommandOutput; rendering uses value.data, json: Boolean(flags.json), and parsed fields.
• 🟡 (16:18) Tool diff showed command finalization appending the automatic cache-age hint to a returned hint, then calling writeFinalization(); bare return; paths such as --web produce no footer because no output was rendered.
• 🟡 (16:18) Tool diff showed error finalization closing streaming state with writeFinalization(stdout, undefined, false, renderer) only in human mode, avoiding corruption of JSON output; afterward maybeRecoverWithHelp() can replace a positional help resolution/validation failure with help output before handleOutputError(err).
• 🟡 (16:18) Tool diff showed buildCommand() retaining the output schema as __jsonSchema for introspect.ts and retaining the original unwrapped generator as __rawFunc for internal dispatchers such as bare sentry auth, avoiding re-entry into telemetry, authentication, rc-trust, and output pipelines.