docs: unify BugBot audit fixes and stop AGENTS.md tree drift (#1050)

## Summary

Consolidates the four recurring Cursor BugBot **"docs:"** audit PRs into
a single set of verified fixes, and removes the *root cause* of the
repeated audits.

Supersedes and closes:
- #972 — comprehensive documentation gap audit report
- #946 — fix documentation gaps identified by automated audit
- #1043 — fix stale architecture tree and phantom `--cause` flag
- #909 — fix documentation gaps identified in comprehensive audit

## Root cause: AGENTS.md tree drift

Every one of those PRs re-fixed the **hand-maintained architecture tree
in `AGENTS.md`**. That tree drifts whenever a command or API module is
added, so the weekly audit keeps re-filing it.

The repo already generates an always-current project-structure tree into
`docs/src/content/docs/contributing.md` via
`script/generate-docs-sections.ts`. This PR **removes the duplicated
tree from `AGENTS.md`** and replaces it with a concise pointer to the
generated tree (plus `ls src/commands/` / `sentry --help`). This
eliminates the recurring audit target permanently.

## Verified fixes harvested from the audits

Each change was verified against current `main` source, not blindly
cherry-picked:

- **`issue.md`** — removed the phantom `sentry issue plan --cause 0`
example. The `--cause` flag does not exist in `plan.ts`; `plan`
automatically runs root-cause analysis (`ensureRootCauseAnalysis`) when
needed. Requirements text updated accordingly. *(from #1043)*
- **`src/lib/env-registry.ts`** — registered `SENTRY_INIT_TUI` (read at
`src/lib/init/ui/factory.ts`) so it surfaces in the generated
`configuration.md`. *(from #946)*
- **`cli.md`** — documented `sentry cli defaults headers` and `sentry
cli defaults ca-cert` (both implemented in `defaults.ts`). *(from #946)*
- **`self-hosted.md`** — documented `auth login --url` as the
recommended, trust-anchoring login method, and added a **TLS / Corporate
Proxies** section (`NODE_EXTRA_CA_CERTS` + `cli defaults
ca-cert`/`headers`). *(from #909)*
- **`getting-started.mdx` / `README.md`** — noted the **Node.js 22.15+**
requirement for npm/pnpm/yarn packages (matches `package.json` engines);
added `yarn` install + `pnpm dlx`/`yarn dlx`/`bunx` run options to the
README. *(from #909/#946)*

Regenerated skill references (`references/issue.md`,
`references/cli.md`) via `pnpm run generate:docs`.

## Discarded

- The throwaway `DOCUMENTATION_GAPS.md` / `docs/DOCUMENTATION_GAPS.md` /
`DOCUMENTATION_GAP_REPORT.md` audit artifacts are **not** committed, and
are now gitignored so future bot audits don't accidentally commit them.
- Skipped items already landed on `main` since the PRs opened (dashboard
`revisions`/`restore` examples, `configuration.md` cross-refs) and the
unverified Cursor `~/.agents` claim that #972 itself flagged as
inaccurate.

## Verification

- `pnpm run typecheck` ✅
- `pnpm run lint` ✅ (only pre-existing unrelated warning in
`formatters/local.ts`)
- `pnpm run check:fragments` ✅ (all 22 fragments valid)
- `pnpm exec vitest run test/lib test/commands test/types` ✅ (5529
passed, 9 skipped)
- Confirmed `SENTRY_INIT_TUI` appears in generated `configuration.md`.

Author: BYK

.gitignore

@@ -72,3 +72,8 @@ docs/public/.well-known/skills/index.json
 # OpenCode
 .opencode/
 opencode.json*
+
+# Throwaway documentation audit reports (bot-generated, not real docs)
+DOCUMENTATION_GAPS.md
+docs/DOCUMENTATION_GAPS.md
+DOCUMENTATION_GAP_REPORT.md

AGENTS.md

@@ -105,132 +105,30 @@ const result = execSync("id -u username", { encoding: "utf-8", stdio: ["pipe", "
 
 ## Architecture
 
-```
-cli/
-├── src/
-│   ├── bin.ts              # Entry point
-│   ├── app.ts              # Stricli application setup
-│   ├── context.ts          # Dependency injection context
-│   ├── commands/           # CLI commands
-│   │   ├── auth/           # login, logout, refresh, status, token, whoami
-│   │   ├── cli/            # defaults, feedback, fix, setup, upgrade
-│   │   ├── dashboard/      # list, view, create, widget (add, edit, delete)
-│   │   ├── event/          # list, view
-│   │   ├── issue/          # list, view, events, explain, plan, resolve, unresolve, merge
-│   │   ├── log/            # list, view
-│   │   ├── org/            # list, view
-│   │   ├── project/        # list, view, create, delete
-│   │   ├── release/        # list, view, create, finalize, delete, deploy, deploys, set-commits, propose-version
-│   │   ├── repo/           # list
-│   │   ├── sourcemap/      # inject, upload
-│   │   ├── span/           # list, view
-│   │   ├── team/           # list
-│   │   ├── trace/          # list, view, logs
-│   │   ├── trial/          # list, start
-│   │   ├── api.ts          # Direct API access command
-│   │   ├── help.ts         # Help command
-│   │   ├── init.ts         # Initialize Sentry in your project (experimental)
-│   │   └── schema.ts       # Browse the Sentry API schema
-│   ├── lib/                # Shared utilities
-│   │   ├── command.ts      # buildCommand wrapper (telemetry + output)
-│   │   ├── api-client.ts   # Barrel re-export for API modules
-│   │   ├── api/            # Domain API modules
-│   │   │   ├── infrastructure.ts # Shared helpers, types, raw requests
-│   │   │   ├── organizations.ts
-│   │   │   ├── projects.ts
-│   │   │   ├── issues.ts
-│   │   │   ├── events.ts
-│   │   │   ├── traces.ts      # Trace + span listing
-│   │   │   ├── logs.ts
-│   │   │   ├── seer.ts
-│   │   │   └── trials.ts
-│   │   ├── region.ts       # Multi-region resolution
-│   │   ├── telemetry.ts    # Sentry SDK instrumentation
-│   │   ├── sentry-urls.ts  # URL builders for Sentry
-│   │   ├── hex-id.ts       # Hex ID validation (32-char + 16-char span)
-│   │   ├── trace-id.ts     # Trace ID validation wrapper
-│   │   ├── db/             # SQLite database layer
-│   │   │   ├── instance.ts     # Database singleton
-│   │   │   ├── schema.ts       # Table definitions
-│   │   │   ├── migration.ts    # Schema migrations
-│   │   │   ├── utils.ts        # SQL helpers (upsert)
-│   │   │   ├── auth.ts         # Token storage
-│   │   │   ├── user.ts         # User info cache
-│   │   │   ├── regions.ts      # Org→region URL cache
-│   │   │   ├── defaults.ts     # Default org/project
-│   │   │   ├── pagination.ts   # Cursor pagination storage
-│   │   │   ├── dsn-cache.ts    # DSN resolution cache
-│   │   │   ├── project-cache.ts    # Project data cache
-│   │   │   ├── project-root-cache.ts # Project root cache
-│   │   │   ├── project-aliases.ts  # Monorepo alias mappings
-│   │   │   └── version-check.ts    # Version check cache
-│   │   ├── dsn/            # DSN detection system
-│   │   │   ├── detector.ts     # High-level detection API
-│   │   │   ├── scanner.ts      # File scanning logic
-│   │   │   ├── code-scanner.ts # Code file DSN extraction
-│   │   │   ├── project-root.ts # Project root detection
-│   │   │   ├── parser.ts       # DSN parsing utilities
-│   │   │   ├── resolver.ts     # DSN to org/project resolution
-│   │   │   ├── fs-utils.ts     # File system helpers
-│   │   │   ├── env.ts          # Environment variable detection
-│   │   │   ├── env-file.ts     # .env file parsing
-│   │   │   ├── errors.ts       # DSN-specific errors
-│   │   │   ├── types.ts        # Type definitions
-│   │   │   └── languages/      # Per-language DSN extractors
-│   │   │       ├── javascript.ts
-│   │   │       ├── python.ts
-│   │   │       ├── go.ts
-│   │   │       ├── java.ts
-│   │   │       ├── ruby.ts
-│   │   │       └── php.ts
-│   │   ├── formatters/     # Output formatting
-│   │   │   ├── human.ts    # Human-readable output
-│   │   │   ├── json.ts     # JSON output
-│   │   │   ├── output.ts   # Output utilities
-│   │   │   ├── seer.ts     # Seer AI response formatting
-│   │   │   ├── colors.ts   # Terminal colors
-│   │   │   ├── markdown.ts # Markdown → ANSI renderer
-│   │   │   ├── trace.ts    # Trace/span formatters
-│   │   │   ├── time-utils.ts # Shared time/duration utils
-│   │   │   ├── table.ts    # Table rendering
-│   │   │   └── log.ts      # Log entry formatting
-│   │   ├── oauth.ts            # OAuth device flow
-│   │   ├── errors.ts           # Error classes
-│   │   ├── resolve-target.ts   # Org/project resolution
-│   │   ├── resolve-issue.ts    # Issue ID resolution
-│   │   ├── issue-id.ts         # Issue ID parsing utilities
-│   │   ├── arg-parsing.ts      # Argument parsing helpers
-│   │   ├── alias.ts            # Alias generation
-│   │   ├── promises.ts         # Promise utilities
-│   │   ├── polling.ts          # Polling utilities
-│   │   ├── upgrade.ts          # CLI upgrade functionality
-│   │   ├── version-check.ts    # Version checking
-│   │   ├── browser.ts          # Open URLs in browser
-│   │   ├── clipboard.ts        # Clipboard access
-│   │   └── qrcode.ts           # QR code generation
-│   └── types/              # TypeScript types and Zod schemas
-│       ├── sentry.ts       # Sentry API types
-│       ├── config.ts       # Configuration types
-│       ├── oauth.ts        # OAuth types
-│       └── seer.ts         # Seer AI types
-├── test/                   # Test files (mirrors src/ structure)
-│   ├── lib/                # Unit tests for lib/
-│   │   ├── *.test.ts           # Standard unit tests
-│   │   ├── *.property.test.ts  # Property-based tests
-│   │   └── db/
-│   │       ├── *.test.ts           # DB unit tests
-│   │       └── *.model-based.test.ts # Model-based tests
-│   ├── model-based/        # Model-based testing helpers
-│   │   └── helpers.ts      # Isolated DB context, constants
-│   ├── commands/           # Unit tests for commands/
-│   ├── e2e/                # End-to-end tests
-│   ├── fixtures/           # Test fixtures
-│   └── mocks/              # Test mocks
-├── docs/                   # Documentation site (Astro + Starlight)
-├── script/                 # Build and utility scripts
-├── .cursor/rules/          # Cursor AI rules (read these!)
-└── biome.jsonc             # Linting config (extends ultracite)
-```
+The full project-structure tree — including the live command/subcommand list and the
+domain API modules — is generated from the route tree and lives in
+[`docs/src/content/docs/contributing.md`](docs/src/content/docs/contributing.md)
+(the `project-structure` block produced by `script/generate-docs-sections.ts`). It is
+kept in sync automatically, so it is **not** duplicated here to avoid drift. For the
+current command list run `ls src/commands/` or `sentry --help`.
+
+Top-level layout:
+
+- **`src/bin.ts`** — entry point; **`src/app.ts`** — Stricli application setup;
+  **`src/context.ts`** — dependency-injection context.
+- **`src/commands/`** — one directory per command group (`auth`, `cli`, `dashboard`,
+  `event`, `issue`, `log`, `org`, `project`, `release`, `replay`, `repo`, `sourcemap`,
+  `span`, `team`, `trace`, `trial`, `local`, …) plus standalone command files
+  (`api.ts`, `explore.ts`, `help.ts`, `init.ts`, `schema.ts`).
+- **`src/lib/`** — shared utilities. Key subtrees: `api/` (domain API modules),
+  `db/` (SQLite layer), `dsn/` (DSN detection, with per-language extractors under
+  `dsn/languages/`), and `formatters/` (output formatting). See the file-locations
+  table below and the JSDoc in each module for details.
+- **`src/types/`** — TypeScript types and Zod schemas.
+- **`test/`** — tests mirroring `src/` (unit, `*.property.test.ts`,
+  `*.model-based.test.ts`, `e2e/`, `fixtures/`, `mocks/`).
+- **`docs/`** — documentation site (Astro + Starlight); **`script/`** — build/utility
+  scripts; **`.cursor/rules/`** — Cursor AI rules; **`biome.jsonc`** — lint config.
 
 ## Key Patterns
 

README.md

@@ -33,13 +33,19 @@ brew install getsentry/tools/sentry
 ```bash
 npm install -g sentry
 pnpm add -g sentry
+yarn global add sentry
 bun add -g sentry
 ```
 
+> The npm/pnpm/yarn packages require Node.js 22.15+.
+
 ### Run Without Installing
 
 ```bash
 npx sentry@latest
+pnpm dlx sentry --help
+yarn dlx sentry --help
+bunx sentry --help
 ```
 
 ## Quick Start

docs/src/content/docs/getting-started.mdx

@@ -54,7 +54,7 @@ brew install getsentry/tools/sentry
 
 ### Package Managers
 
-Install globally with your preferred package manager:
+Install globally with your preferred package manager (the npm/pnpm/yarn packages require **Node.js 22.15+**):
 
 <PackageManagerCode
   npm="npm install -g sentry"

docs/src/content/docs/self-hosted.md

@@ -24,7 +24,13 @@ The OAuth device flow requires **Sentry 26.1.0 or later** and a public OAuth app
 
 #### 2. Log In
 
-Pass your instance URL and the client ID:
+Use the `--url` flag to authenticate against your instance (recommended — this registers the host as trusted):
+
+```bash
+SENTRY_CLIENT_ID=your-client-id sentry auth login --url https://sentry.example.com
+```
+
+Or pass the instance URL via environment variable:
 
 ```bash
 SENTRY_HOST=https://sentry.example.com SENTRY_CLIENT_ID=your-client-id sentry auth login
@@ -39,6 +45,10 @@ export SENTRY_CLIENT_ID=your-client-id
 ```
 :::
 
+:::note
+The `--url` flag is the most secure way to authenticate with a new host — it is the only way to register a trust anchor for that host. Without it, the CLI refuses to log in to an instance URL that was picked up from an untrusted channel (e.g. a `.sentryclirc` file), protecting you from credential leaks and OAuth phishing.
+:::
+
 ### With an API Token
 
 If your instance is on an older version or you prefer not to create an OAuth application, you can use an API token instead:
@@ -65,6 +75,26 @@ sentry org list
 
 If you pass a self-hosted Sentry URL as a command argument (e.g., an issue or event URL), the CLI detects the instance automatically.
 
+## TLS / Corporate Proxies
+
+If your self-hosted instance sits behind a private CA certificate (common with corporate TLS-intercepting proxies like Zscaler or Netskope), point `NODE_EXTRA_CA_CERTS` at your CA bundle:
+
+```bash
+export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
+```
+
+You can also persist this so you don't need the env var on every invocation:
+
+```bash
+sentry cli defaults ca-cert /path/to/corporate-ca.pem
+```
+
+If your proxy requires custom HTTP headers (e.g. an IAP token), set them with `SENTRY_CUSTOM_HEADERS` or persist them:
+
+```bash
+sentry cli defaults headers "X-IAP: token"
+```
+
 ## Relevant Environment Variables
 
 <!-- GENERATED:START self-hosted-env-vars -->

docs/src/fragments/commands/cli.md

@@ -76,6 +76,12 @@ sentry cli defaults project my-project
 # Set default Sentry URL (self-hosted)
 sentry cli defaults url https://sentry.example.com
 
+# Set custom HTTP headers (self-hosted, e.g. for IAP/proxies)
+sentry cli defaults headers "X-IAP: token"
+
+# Set a custom CA certificate (self-hosted, behind a TLS proxy)
+sentry cli defaults ca-cert /path/to/ca.pem
+
 # Disable telemetry
 sentry cli defaults telemetry off
 

docs/src/fragments/commands/issue.md

@@ -131,19 +131,19 @@ sentry issue explain my-org/MYPROJECT-ABC
 # Force a fresh analysis
 sentry issue explain 123456789 --force
 
-# Generate a fix plan (requires explain to be run first)
+# Generate a fix plan (automatically runs explain if needed)
 sentry issue plan 123456789
 
-# Specify which root cause to plan for
-sentry issue plan 123456789 --cause 0
+# Force a fresh plan even if one already exists
+sentry issue plan 123456789 --force
 ```
 
 **Requirements:**
 
 - Seer AI enabled for your organization
 - GitHub integration configured with repository access
 - Code mappings set up to link stack frames to source files
-- Root cause analysis must be completed (`sentry issue explain`) before generating a plan
+- Root cause analysis is run automatically if needed (the `plan` command triggers `explain` first)
 
 ### Resolve and reopen issues
 

plugins/sentry-cli/skills/sentry-cli/references/cli.md

@@ -35,6 +35,12 @@ sentry cli defaults project my-project
 # Set default Sentry URL (self-hosted)
 sentry cli defaults url https://sentry.example.com
 
+# Set custom HTTP headers (self-hosted, e.g. for IAP/proxies)
+sentry cli defaults headers "X-IAP: token"
+
+# Set a custom CA certificate (self-hosted, behind a TLS proxy)
+sentry cli defaults ca-cert /path/to/ca.pem
+
 # Disable telemetry
 sentry cli defaults telemetry off
 

plugins/sentry-cli/skills/sentry-cli/references/issue.md

@@ -159,11 +159,11 @@ sentry issue explain my-org/MYPROJECT-ABC
 # Force a fresh analysis
 sentry issue explain 123456789 --force
 
-# Generate a fix plan (requires explain to be run first)
+# Generate a fix plan (automatically runs explain if needed)
 sentry issue plan 123456789
 
-# Specify which root cause to plan for
-sentry issue plan 123456789 --cause 0
+# Force a fresh plan even if one already exists
+sentry issue plan 123456789 --force
 ```
 
 ### `sentry issue plan <issue>`

src/lib/env-registry.ts

@@ -175,6 +175,13 @@ export const ENV_VAR_REGISTRY: readonly EnvVarEntry[] = [
     example: "1",
     installOnly: true,
   },
+  // -- Init wizard --
+  {
+    name: "SENTRY_INIT_TUI",
+    description:
+      "Control the TUI (terminal user interface) for `sentry init`. Set to `0` to disable the interactive TUI and use plain text logging output instead. Useful in CI/CD pipelines or environments without full terminal support.",
+    example: "0",
+  },
   // -- TLS / Certificates --
   {
     name: "NODE_EXTRA_CA_CERTS",