docs: fix auth token precedence, update stale architecture tree, and documentation audit report

AGENTS.md

@@ -112,18 +112,25 @@ cli/
 │   ├── app.ts              # Stricli application setup
 │   ├── context.ts          # Dependency injection context
 │   ├── commands/           # CLI commands
-│   │   ├── auth/           # login, logout, status, refresh
-│   │   ├── event/          # view
-│   │   ├── issue/          # list, view, explain, plan
+│   │   ├── 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
+│   │   ├── 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
-│   │   ├── log/            # list, view
 │   │   ├── trial/          # list, start
-│   │   ├── cli/            # fix, upgrade, feedback, setup
 │   │   ├── api.ts          # Direct API access command
-│   │   └── help.ts         # Help 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

DEVELOPMENT.md

@@ -69,11 +69,15 @@ When creating your Sentry OAuth application:
 
 ## Environment Variables
 
-| Variable           | Description                                           | Default              |
-| ------------------ | ----------------------------------------------------- | -------------------- |
-| `SENTRY_CLIENT_ID` | Sentry OAuth app client ID                            | (required)           |
-| `SENTRY_HOST`      | Sentry instance URL (for self-hosted, takes precedence) | `https://sentry.io`  |
-| `SENTRY_URL`       | Alias for `SENTRY_HOST`                               | `https://sentry.io`  |
+| Variable                | Description                                                      | Default              |
+| ----------------------- | ---------------------------------------------------------------- | -------------------- |
+| `SENTRY_CLIENT_ID`      | Sentry OAuth app client ID                                       | (required for build) |
+| `SENTRY_HOST`           | Sentry instance URL (for self-hosted, takes precedence)          | `https://sentry.io`  |
+| `SENTRY_URL`            | Alias for `SENTRY_HOST`                                          | `https://sentry.io`  |
+| `SENTRY_AUTH_TOKEN`     | API token for non-interactive use (lower priority than stored OAuth by default) | —     |
+| `SENTRY_FORCE_ENV_TOKEN`| Force env token to take priority over stored OAuth token         | —                    |
+| `SENTRY_CLI_NO_TELEMETRY`| Disable CLI telemetry (error tracking)                          | —                    |
+| `SENTRY_LOG_LEVEL`      | Diagnostic log level (`error`, `warn`, `log`, `info`, `debug`, `trace`) | `info`        |
 
 ## Building
 

docs/src/content/docs/agentic-usage.md

@@ -3,11 +3,17 @@ title: Agentic Usage
 description: Enable AI coding agents to use the Sentry CLI
 ---
 
-AI coding agents like Claude Code can use the Sentry CLI through the skill system. This allows agents to interact with Sentry directly from your development environment.
+AI coding agents like Claude Code and Cursor can use the Sentry CLI through the skill system. This allows agents to interact with Sentry directly from your development environment.
 
-## Adding the Skill
+## Automatic Installation
 
-Add the Sentry CLI skill to your agent:
+When you install the CLI (via `curl`, Homebrew, or a package manager), `sentry cli setup` automatically installs agent skills into any detected agent root directories (`~/.claude`, `~/.agents`). Skills are also refreshed on `sentry cli upgrade`. No network fetch is needed — skill files are embedded in the binary.
+
+To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup`.
+
+## Manual Installation
+
+Add the Sentry CLI skill to your agent manually:
 
 ```bash
 npx skills add https://cli.sentry.dev
@@ -43,4 +49,4 @@ The skill uses your existing CLI authentication, so you'll need to run `sentry a
 ## Requirements
 
 - An authenticated Sentry CLI installation (`sentry auth login`)
-- An AI coding agent that supports the skills system (e.g., Claude Code)
+- An AI coding agent that supports the skills system (e.g., Claude Code, Cursor, or any agent using `~/.agents`)

docs/src/fragments/commands/auth.md

@@ -76,12 +76,14 @@ sentry auth whoami
 
 Auth tokens are stored in a SQLite database at `~/.sentry/cli.db` with restricted file permissions.
 
-## Environment Variable Precedence
+## Token Precedence
 
-The CLI checks for auth tokens in the following order, using the first one found:
+By default, the CLI checks for auth tokens in the following order:
 
-1. `SENTRY_AUTH_TOKEN` environment variable
-2. `SENTRY_TOKEN` environment variable (legacy alias)
-3. The stored OAuth token in the SQLite database
+1. The stored OAuth token in the SQLite database (from `sentry auth login`)
+2. `SENTRY_AUTH_TOKEN` environment variable
+3. `SENTRY_TOKEN` environment variable (legacy alias)
+
+The stored OAuth token takes priority because it supports automatic refresh. To override this and force environment tokens to win, set `SENTRY_FORCE_ENV_TOKEN=1`.
 
 When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh.

src/lib/env-registry.ts

@@ -32,7 +32,7 @@ export const ENV_VAR_REGISTRY: readonly EnvVarEntry[] = [
   {
     name: "SENTRY_AUTH_TOKEN",
     description:
-      "Authentication token for the Sentry API. This is the primary way to authenticate in CI/CD pipelines and scripts where interactive login is not possible.\n\nYou can create auth tokens in your [Sentry account settings](https://sentry.io/settings/account/api/auth-tokens/). When set, this takes precedence over any stored OAuth token from `sentry auth login`.",
+      "Authentication token for the Sentry API. This is the primary way to authenticate in CI/CD pipelines and scripts where interactive login is not possible.\n\nYou can create auth tokens in your [Sentry account settings](https://sentry.io/settings/account/api/auth-tokens/). By default, a stored OAuth token from `sentry auth login` takes priority over this variable. Set `SENTRY_FORCE_ENV_TOKEN=1` to give environment tokens precedence instead.",
     example: "sntrys_YOUR_TOKEN_HERE",
   },
   {