Distillation

Date: Sep 8, 2026

• 🔴 (20:13) User established that buildListCommand() in packages/cli/src/lib/list-command.ts must always inject --fresh unless the command already defines a fresh flag.
• 🔴 (20:13) User established that the first positional argument handled by buildListCommand() is always the target using the org/project pattern.
• 🟡 (20:13) buildListCommand() automatically intercepts plural-alias subcommand confusion, injects --fresh and --cursor unless already defined, injects aliases -f and -c, and calls applyFreshFlag(flags) before the original command function. ListCommandOptions.noCursorFlag suppresses --cursor and -c; ListCommandOptions.noFreshAlias suppresses -f.
• 🟡 (20:13) Shared list-command values in packages/cli/src/lib/list-command.ts are LIST_MAX_LIMIT = 1000, LIST_MIN_LIMIT = 1, and LIST_DEFAULT_LIMIT = 25; the Sentry API silently caps per_page at 100, so commands auto-paginate to satisfy larger limits up to the CLI ceiling.
• 🟡 (20:13) LIST_TARGET_POSITIONAL is an optional tuple positional with placeholder org/project; it accepts <org>/ for all projects, <org>/<project> for an explicit target, or bare <project> for project search, with omission falling back to auto-detection.
• 🟡 (20:13) TARGET_PATTERN_NOTE explains that a bare name without / triggers project search and <org>/<project> is required for an explicit target. targetPatternExplanation() emphasizes that the trailing slash in <org>/ is significant and can append a cursor-specific note.
• 🟡 (20:13) buildOrgListCommand() delegates through buildListCommand(), uses LIST_TARGET_POSITIONAL, parses the target with parseOrgProjectArg(), calls dispatchOrgScopedList() with orgSlugMatchBehavior: "redirect", yields CommandOutput(result), and forwards result.hint as a footer only when results contain items.
• 🟡 (20:14) PR #1558 at commit bbaa7b3b722b87f1bccfe84063269cbbcabe2741 had passing checks for Cursor Bugbot (2m25s), Seer Code Review (2m20s), Socket Security Project Report (13s), Socket Security Pull Request Alerts (2s), and semgrep-cloud-platform/scan (1m52s). Vercel failed with “Authorization required to deploy” because a Sentry Team member needed to authorize @alicandayan’s deployment; this was an authorization issue rather than a reported code failure.
• 🟡 (20:14) Copilot review 5143168998 left one comment on packages/cli/src/commands/agent-conversation/list.ts: customUsage: ["[<org>]"] documents an optional org, but the runtime ContextError still suggests sentry agent-conversation list <org>, misleading users when org auto-detection fails. Copilot recommended updating the runtime usage hint or deriving it from the same source as generated docs.
• 🟡 (20:14) Copilot summarized PR #1558 as correcting sentry agent-conversation view to use the single positional [<org>/]<conversation-id>, clarifying org auto-detection for list and view, adding customUsage metadata, updating generated skill/docs examples to conv-123 and my-org/conv-123, and adding regression tests for optional-org headings and the single-positional form.
• 🔴 (20:14) User established that atomicWriteFile() in packages/cli/src/lib/agent-skills.ts must ensure a concurrent reader never observes a truncated or partially written skill file.
• 🔴 (20:14) User established that the temporary file used by atomicWriteFile() must never match the SKILL.md or *.md discovery globs used by agents.
• 🟡 (20:14) atomicWriteFile() writes beside the destination to .<basename>.<pid>.<rand>.tmp, using writeFile(tempPath, content, "utf-8") followed by rename(tempPath, destPath). Same-directory placement makes replacement atomic on POSIX; on Windows replacement can transiently fail with a sharing violation if a reader holds the destination open.
• 🟡 (20:14) If atomicWriteFile() fails, it best-effort removes the temporary file with rm(tempPath, { force: true }), reports cleanup failures through captureException() at level "debug" with tag "setup.step": "agent-skills-cleanup", and rethrows the original error.
• 🔴 (20:14) User established that installAgentSkills() never creates top-level agent roots; pre-existing ~/.agents or ~/.claude directories are the detection signal that a compatible coding agent is installed.
• 🟡 (20:14) packages/cli/src/lib/agent-skills.ts supports installation beneath .agents and .claude; getSkillInstallPath(homeDir, rootDir) resolves to <home>/<root>/skills/sentry-cli/SKILL.md, with .claude as the default root, and detectClaudeCode() checks for <home>/.claude.
• 🟡 (20:14) writeSkillFiles() iterates over embedded SKILL_FILES, recursively creates missing directories with mode 0o755, atomically writes each file, counts paths beginning with references/, and returns { path, created: !alreadyExists, referenceCount }. Filesystem failures are captured at warning level with tag "setup.step": "agent-skills" and return null.
• 🟡 (20:14) installAgentSkills() checks .agents before .claude, skips undetected roots, and verifies each existing root is writable with accessSync(parentDir, constants.W_OK) before attempting installation because some sandboxed environments may terminate on write attempts rather than exposing a catchable JavaScript error.
• 🟡 (20:14) Public agent-skill discovery is present under apps/cli-docs/public/.well-known/skills/, containing index.json and sentry-cli/; the latter contains SKILL.md and references/.
• 🟡 (20:14) apps/cli-docs/public/.well-known/skills/index.json defines skill sentry-cli with 37 files total: SKILL.md plus 36 references, in order: 1. references/agent-conversation.md, 2. references/alert.md, 3. references/api.md, 4. references/auth.md, 5. references/build.md, 6. references/cli.md, 7. references/code-mappings.md, 8. references/dart-symbol-map.md, 9. references/dashboard.md, 10. references/debug-files.md, 11. references/docs.md, 12. references/event.md, 13. references/explore.md, 14. references/feedback.md, 15. references/info.md, 16. references/init.md, 17. references/issue.md, 18. references/local.md, 19. references/log.md, 20. references/monitor.md, 21. references/org.md, 22. references/platform.md, 23. references/proguard.md, 24. references/project.md, 25. references/react-native.md, 26. references/release.md, 27. references/replay.md, 28. references/repo.md, 29. references/schema.md, 30. references/snapshots.md, 31. references/sourcemap.md, 32. references/span.md, 33. references/status.md, 34. references/team.md, 35. references/trace.md, 36. references/trial.md.