Distillation

Date: Sep 8, 2026

• 🔴 (22:27) User stated the repository root is /home/byk/Code/getsentry/cli-pr-1558; it contains 18 entries: .craft.yml, .git, .github/, .gitignore, .lore.md, .nojekyll, .npmrc, AGENTS.md, apps/, CHANGELOG.md, codemods/, LICENSE.md, node_modules/, package.json, packages/, pnpm-lock.yaml, pnpm-workspace.yaml, and README.md.
• 🔴 (22:27) User provided applicable repository instructions from /home/byk/Code/getsentry/cli-pr-1558/AGENTS.md, /home/byk/Code/getsentry/cli-pr-1558/packages/cli/AGENTS.md, and /home/byk/Code/getsentry/cli-pr-1558/packages/cli/CONTRIBUTING.md; target repositories require reading their AGENTS.md / CONTRIBUTING.md first.
• 🔴 (22:27) User requires always loading repo-setup before situation skills; skills live under .agents/skills/, are generated from canonical skills/, and are synchronized by scripts/sync-skills.mjs.
• 🔴 (22:27) User requires always checking package.json for the latest scripts. Commands run from packages/cli, or from the repository root via pnpm --filter sentry run <script>.
• 🔴 (22:27) User stated Sentry CLI is a Node.js, pnpm, and Stricli project located in packages/cli; the Astro + Starlight documentation site is in apps/cli-docs.
• 🔴 (22:27) User requires all packages to be placed in devDependencies, never dependencies, because esbuild bundles everything at build time and CI enforces this with pnpm run check:deps.
• 🔴 (22:27) User requires adding packages with the exact command pnpm add -D <package>, including the -D flag.
• 🔴 (22:27) User requires Node.js node:* APIs and prohibits reintroducing Bun.* globals, bun:test, or bun CLI commands because the project migrated from Bun to Node.js.
• 🔴 (22:27) User requires preferring execFileSync/execFile with array arguments over string-based execSync when passing user-controlled values, to avoid shell injection.
• 🔴 (22:27) User requires command implementations to import buildCommand from ../../lib/command.js, never directly from @stricli/core; the wrapper adds telemetry, injects --json/--fields, and handles output rendering.
• 🔴 (22:27) User requires command functions to use async *func() generators, yield new CommandOutput(data), and optionally return { hint }; commands must not add their own json flag, branch on flags.json, or call stdout.write().
• 🔴 (22:27) User requires route groups to import buildRouteMap from ../../lib/route-map.js, never directly from @stricli/core; the wrapper auto-adds aliases list → ls, view → show, delete → remove, rm, and create → new, and these standard aliases must not be manually duplicated.
• 🔴 (22:27) User stated required positional multi-values are space-separated variadics and must not be comma-split, while optional flag multi-values are comma-separated and may also be repeatable.
• 🔴 (22:27) User requires all non-trivial human output to use the Markdown rendering pipeline with helpers such as mdKvTable(), colorTag(), escapeMarkdownCell(), and renderMarkdown(); raw muted()/chalk must not be embedded in output strings.
• 🔴 (22:27) User stated isPlainOutput() precedence is SENTRY_PLAIN_OUTPUT > NO_COLOR > FORCE_COLOR (TTY only) > !isTTY; its implementation is in src/lib/formatters/plain-detect.ts and is re-exported from markdown.ts.
• 🔴 (22:27) User requires delete commands to use buildDeleteCommand() from src/lib/mutate-command.ts; it injects --yes, --force, and --dry-run with aliases -y, -f, and -n, and blocks non-interactive execution without --yes/--force unless dry-run bypasses the guard.
• 🔴 (22:27) User requires API-paginated list commands to use the shared cursor-stack infrastructure for bidirectional pagination via -c next / -c prev, including resolveCursor, advancePaginationState, hasPreviousPage, and paginationHint() at the appropriate abstraction level.
• 🔴 (22:27) User stated the three preferred list-command abstraction levels, in order: 1. buildOrgListCommand for fully automatic simple organization-scoped lists, 2. dispatchOrgScopedList with overrides for mostly automatic commands with custom modes, 3. buildListCommand with manual pagination for commands such as trace/span/dashboard lists.
• 🔴 (22:27) User requires list commands whose --limit exceeds API_MAX_PER_PAGE (100) to transparently fetch multiple pages, using Math.min(flags.limit, API_MAX_PER_PAGE) and looping until results.length >= limit or pages are exhausted.
• 🔴 (22:27) User requires never passing a per_page value larger than API_MAX_PER_PAGE to the API; the server silently caps oversized values, which otherwise causes commands to return fewer items than requested.
• 🔴 (22:27) User requires generated command docs and skills to be produced through pnpm run generate:docs, which runs generate:command-docs and then generate:skill; generation also runs during dev, build, typecheck, and test.
• 🔴 (22:27) User stated command docs at docs/src/content/docs/commands/*.md are gitignored and generated from CLI metadata plus fragments in docs/src/fragments/commands/; skill files under plugins/sentry-cli/skills/sentry-cli/ are committed and CI auto-commits them when stale.
• 🔴 (22:27) User requires editing docs/src/fragments/commands/ for custom examples and guides, validating fragment-to-route consistency with pnpm run check:fragments, and using descriptive positional placeholders such as "org/project/trace-id" rather than "args".