Distillation

Date: Sep 9, 2026

• 🔴 (18:38) User stated --fields is always injected when output: { human: ... }, even when a command already defines its own json flag and the injected JSON_FLAG is skipped.
• 🔴 (18:38) User stated flags in ALWAYS_STRIP are always stripped so the command never sees them; ALWAYS_STRIP currently contains LOG_LEVEL_KEY.
• 🔴 (18:38) User directed list-command construction to always inject --fresh unless the command already defines a fresh flag; injected definition is FRESH_FLAG.
• 🔴 (18:38) User stated the first positional argument for list commands is always the target, following the org/project pattern, and should be passed through interceptSubcommand() to handle plural-alias confusion.
• 🟡 (18:38) packages/cli/src/lib/command.ts builds a schema-aware --fields flag via buildFieldsFlag(outputConfig?): when outputConfig.schema yields fields from extractSchemaFields(), the flag brief appends Available: ${fieldNames}; absent or empty schemas fall back to FIELDS_FLAG.
• 🟡 (18:38) packages/cli/src/lib/command.ts enriches Stricli help through enrichDocsWithSchema(): schema field names/types from formatSchemaForHelp(schemaFields) are appended to docs.fullDescription, using docs.fullDescription ?? docs.brief as the base.
• 🟡 (18:38) buildCommandInfo(cmd, path, examples) exposes JSON schema fields by calling extractSchemaFields(cmd.__jsonSchema) when cmd.__jsonSchema exists.
• 🟡 (18:38) Help typo recovery handles positional values "help", "--h", and "-help" only after a command throws a CliError; it shows command help rather than the original confusing error. Legitimate successful values such as a project named "help" remain unaffected, and OutputError is excluded so its renderable data reaches handleOutputError.
• 🟡 (18:38) FRESH_FLAG is a boolean read-only-command flag with alias -f, default false, and brief "Bypass cache, re-detect projects, and fetch fresh data"; commands activate it through applyFreshFlag(flags).
• 🟡 (18:38) Subcommand detection may fail under Vitest because require("../app.js") cannot resolve .js to .ts for transitive imports. The implementation catches the error, logs "Failed to load app routes for subcommand detection", and degrades by treating targets as plain values without subcommand interception.
• 🟡 (18:38) .github/workflows/pr-risk.yml changed getsentry/pr-risk-action@v0 input apply-label from "true" to ${{ github.event.pull_request.head.repo.full_name == github.repository }}, allowing labels only when the pull request head repository is the current repository and thereby skipping label application for fork PRs.
• 🟡 (18:39) Search of .github/workflows/pr-risk.yml found exactly 2 relevant matches: line 24 uses getsentry/pr-risk-action@v0; line 30 sets apply-label: ${{ github.event.pull_request.head.repo.full_name == github.repository }}.
• 🟡 (18:39) Search of packages/cli/src/lib/command.ts found 17 documentation-related matches: CommandExample line 98; canonical-signature comment for customUsage line 107; CommandDocumentation line 110; examples line 113; docs line 154; documentation processing around lines 421 and 424; prepareNativeDocs lines 441–442; attachDocumentationMetadata lines 459, 461, and 464; docs.customUsage?.[0] line 464; metadata.__examples = docs.examples line 470; enrichDocsWithSchema lines 563–564; command docs: stricliDocs line 885; and attachDocumentationMetadata(cmd, builderArgs.docs) line 890.