docs: align install, auth, config, and dev docs with current CLI behavior

AGENTS.md

@@ -1,29 +1,10 @@
-# Jared (Outpost agent)
+# AGENTS.md
 
-Autonomous GitHub coding agent. Work in `/workspace/repo`.
+This repository is a pnpm workspace. Guidelines for AI agents working on the
+Sentry CLI live in [`packages/cli/AGENTS.md`](packages/cli/AGENTS.md).
 
-## Model tiers
+<!-- This section is maintained by the coding agent via lore (https://github.com/BYK/loreai) -->
+## Long-term Knowledge
 
-The primary model is chosen per event (see `src/agents/models.ts`): heavy for
-code-producing situations, cheaper for lightweight ones.
-
-| Role | Subagent | Model |
-| --- | --- | --- |
-| Triage / plan / review (heavy) | (primary Jared) | Claude Opus 4.8 |
-| Triage / plan / review (light) | (primary Jared) | xAI Grok 4.3 |
-| Explore | `explore` | OpenAI gpt-5-mini |
-| Implement | `implement` | Moonshot kimi-k2.7-code |
-| Ship (commit/push/PR) | `ship` | xAI Grok (`grok-build-0.1`) |
-
-Pipeline: triage → explore → plan → implement → review → ship.
-(`worker` is a deprecated alias of `implement`.)
-
-Operators also talk to Jared directly from the Outpost dashboard. Those turns
-(`New operator chat` / `Operator guidance:`) skip triage — treat the request as
-the task and answer in the conversation.
-
-Long-term project knowledge for *this* Outpost repo lives in `.lore.md` when present.
-For target repositories, read their `AGENTS.md` / `CONTRIBUTING.md` first.
-
-Skills are under `.agents/skills/`, generated from the canonical `skills/` tree
-by `scripts/sync-skills.mjs`. Always load `repo-setup` before situation skills.
+For long-term knowledge entries managed by [lore](https://github.com/BYK/loreai) (gotchas, patterns, decisions, architecture), see [`.lore.md`](.lore.md) in the project root.
+<!-- End lore-managed section -->

README.md

@@ -9,6 +9,8 @@ the Sentry CLI and Sentry MCP server into a single `getsentry/toolkit` monorepo.
   binary `sentry`). See [packages/cli/README.md](./packages/cli/README.md).
 - [`apps/cli-docs/`](./apps/cli-docs) — the CLI documentation site
   (Astro + Starlight, published to `cli.sentry.dev`).
+- [`apps/local/`](./apps/local) — the Sentry Local UI used by `sentry local --open`
+  (Vite + React, published to `local.sentry.dev`).
 
 ## Development
 

apps/cli-docs/src/content/docs/agent-guidance.md

@@ -34,7 +34,7 @@ The `sentry` CLI follows conventions from well-known tools — if you're familia
 
 ## Safety Rules
 
-- Always confirm with the user before running destructive commands: `project delete`, `trial start`
+- Always confirm with the user before running destructive commands: `project delete`, `release delete`, `alert issues delete`, `alert metrics delete`, `dashboard widget delete`, `issue merge`, `trial start`
 - For mutations, verify the org/project context looks correct in the command output before proceeding with further changes
 - Never store or log authentication tokens — the CLI manages credentials automatically
 - If the CLI reports the wrong org/project, override with explicit `<org>/<project>` arguments

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

@@ -3,15 +3,15 @@ title: Agentic Usage
 description: Enable AI coding agents to use the Sentry CLI
 ---
 
-AI coding agents can use the Sentry CLI through the skill system. The CLI detects and supports Claude Code (including Cowork), Cursor, Windsurf, GitHub Copilot, Gemini CLI, OpenAI Codex, Goose, Amp, Augment, OpenCode, Cline, Grok, Kimi, Junie, OpenClaw, and any agent that reads skills from `~/.agents`. This allows agents to interact with Sentry directly from your development environment.
+AI coding agents can use the Sentry CLI through the skill system. The CLI detects and supports Claude Code (including Cowork), Cursor, Windsurf, GitHub Copilot, Gemini CLI, OpenAI Codex, Antigravity, Goose, Amp, Augment, OpenCode, Cline, Grok, Kimi, Junie, OpenClaw, and any agent that reads skills from `~/.agents`. This allows agents to interact with Sentry directly from your development environment.
 
 ## Automatic Installation
 
-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.
+`sentry cli setup` installs the agent skill into the `~/.claude` and `~/.agents` directories when they already exist (the CLI never creates them). The install script and Homebrew run setup for you; after an npm, pnpm, yarn, or bun install, run `sentry cli setup` once. Skills are also refreshed on `sentry cli upgrade`. No network fetch is needed — skill files are embedded in the binary.
 
 This uses the same `~/.agents` convention as [dotagents](https://github.com/getsentry/dotagents), Sentry's first-party tool for installing agent skills. See [Manual Installation](#manual-installation) to add the skill with dotagents yourself.
 
-To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup`.
+To skip automatic skill installation, pass `--no-agent-skills` to the install script, `sentry cli setup`, or `sentry cli upgrade`. The opt-out is remembered for future upgrades; turn installation back on with `sentry cli defaults agent-skills on`.
 
 ## Manual Installation
 

apps/cli-docs/src/content/docs/contributing.md

@@ -25,8 +25,12 @@ cd cli
 # Install dependencies
 pnpm install
 
+# Generate build-time files (API schema, search parser, docs, skills)
+pnpm run generate:schema
+pnpm run generate:docs
+
 # Run CLI in development mode
-pnpm run cli -- --help
+pnpm run cli --help
 
 # Run tests
 pnpm run test
@@ -37,16 +41,22 @@ pnpm run test
 Create a `.env.local` file for development:
 
 ```bash
-cp .env.example .env.local
+cp packages/cli/.env.example packages/cli/.env.local
 ```
 
-Edit `.env.local` with your development credentials.
+Edit `.env.local` with your development credentials. `pnpm run cli` loads it
+automatically. See [DEVELOPMENT.md](https://github.com/getsentry/cli/blob/main/packages/cli/DEVELOPMENT.md)
+for when `SENTRY_CLIENT_ID` is needed.
 
 ## Project Structure
 
+The repository is a pnpm workspace. The CLI lives in `packages/cli/`, the
+documentation site (Astro + Starlight) in `apps/cli-docs/`, and the Sentry
+Local UI in `apps/local/`.
+
 <!-- GENERATED:START project-structure -->
 ```
-cli/
+packages/cli/
 ├── src/
 │   ├── bin.ts          # Entry point
 │   ├── app.ts          # Stricli application setup
@@ -94,8 +104,7 @@ cli/
 │   └── types/          # TypeScript types and Valibot schemas
 ├── test/               # Test files (mirrors src/ structure)
 ├── script/             # Build and utility scripts
-├── plugins/            # Agent skill files
-└── docs/               # Documentation site (Astro + Starlight)
+└── plugins/            # Agent skill files
 ```
 <!-- GENERATED:END project-structure -->
 
@@ -117,17 +126,18 @@ pnpm run bundle
 ## Testing
 
 ```bash
-# Run all tests
+# Run all unit tests (regenerates docs and the SDK first, with coverage)
 pnpm run test
 
-# Run specific test file
-pnpm run test -- test/path/to/test.ts
+# Run a specific test file (path relative to packages/cli; skips the
+# generate steps, so run `pnpm run test` once first)
+pnpm --filter sentry exec vitest run test/path/to/test.ts
 
-# Run with watch mode
-pnpm run test -- --watch
+# Run in watch mode
+pnpm --filter sentry exec vitest
 
-# Run with coverage
-pnpm run test -- --coverage
+# Run end-to-end tests
+pnpm run test:e2e
 ```
 
 ## Code Style

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

@@ -20,17 +20,18 @@ curl https://cli.sentry.dev/install -fsS | bash -s -- --version nightly
 ```
 
 You can also use the `SENTRY_VERSION` environment variable to pin a version,
-which is especially useful in CI/CD pipelines and Dockerfiles:
+which is especially useful in CI/CD pipelines and Dockerfiles. Set it on the
+`bash` side of the pipe (or `export` it) so the installer can read it:
 
 ```bash
 # Pin to a specific stable version
-SENTRY_VERSION=0.42.2 curl https://cli.sentry.dev/install -fsS | bash
+curl https://cli.sentry.dev/install -fsS | SENTRY_VERSION=0.42.2 bash
 
 # Pin to nightly
-SENTRY_VERSION=nightly curl https://cli.sentry.dev/install -fsS | bash
+curl https://cli.sentry.dev/install -fsS | SENTRY_VERSION=nightly bash
 ```
 
-The `--version` flag takes precedence over `SENTRY_VERSION` if both are set.
+The `--version` flag (short form `-v`) takes precedence over `SENTRY_VERSION` if both are set.
 The chosen channel is persisted so that `sentry cli upgrade` automatically
 tracks the same channel on future updates.
 
@@ -52,9 +53,17 @@ curl https://cli.sentry.dev/install -fsS | bash -s -- --no-agent-skills
 You can also set `SENTRY_INSTALL_DIR` to override the binary installation directory:
 
 ```bash
-SENTRY_INSTALL_DIR=~/.local/bin curl https://cli.sentry.dev/install -fsS | bash
+curl https://cli.sentry.dev/install -fsS | SENTRY_INSTALL_DIR=~/.local/bin bash
 ```
 
+Set `SENTRY_INIT=1` to launch the [`sentry init`](../commands/init/) setup wizard right after installation:
+
+```bash
+curl https://cli.sentry.dev/install -fsS | SENTRY_INIT=1 bash
+```
+
+The install script reports installation failures to Sentry. Set `SENTRY_CLI_NO_TELEMETRY=1` to opt out.
+
 ### Supported Platforms
 
 {/* GENERATED:START platform-support */}
@@ -172,13 +181,15 @@ sentry auth logout
 
 ## Self-Hosted Sentry
 
-Using a self-hosted Sentry instance? Set `SENTRY_URL` to point at it:
+Using a self-hosted Sentry instance? Pass its URL with `--url` when you log in:
 
 ```bash
-SENTRY_URL=https://sentry.example.com sentry auth
+sentry auth login --url https://sentry.example.com
 ```
 
-See the [Self-Hosted](../self-hosted/) guide for full setup details.
+`--url` saves the instance as your default URL, so later commands don't need
+`SENTRY_URL`. OAuth login on self-hosted also requires `SENTRY_CLIENT_ID`; see
+the [Self-Hosted](../self-hosted/) guide for full setup details.
 
 ## Configuration
 

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

@@ -20,7 +20,7 @@ The OAuth device flow requires **Sentry 26.1.0 or later** and a public OAuth app
 1. In your Sentry instance, go to **Settings → Developer Settings → Applications → Create New Application** (or visit `https://sentry.example.com/settings/account/api/applications/`)
 2. Select **Public** as the application type
 3. Fill in the required fields (name, redirect URL — can be any placeholder URL)
-3. Save the application and copy the **Client ID**
+4. Save the application and copy the **Client ID**
 
 #### 2. Log In
 
@@ -66,13 +66,19 @@ SENTRY_HOST=https://sentry.example.com sentry auth login --token YOUR_TOKEN
 
 ## After Login
 
-Once authenticated, the CLI stores your instance URL — you don't need to set `SENTRY_URL` on every command. All subsequent commands automatically use the correct instance:
+When you log in with `--url`, the CLI saves the instance URL as your default (the same setting as `sentry cli defaults url`), so you don't need to set `SENTRY_HOST` or `SENTRY_URL` on every command. All subsequent commands automatically use the correct instance:
 
 ```bash
 sentry issue list
 sentry org list
 ```
 
+If you logged in by setting `SENTRY_HOST`/`SENTRY_URL` instead, the URL is not saved. Keep the variable set, or persist it:
+
+```bash
+sentry cli defaults url https://sentry.example.com
+```
+
 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

apps/cli-docs/src/fragments/commands/alert.md

@@ -49,8 +49,8 @@ sentry alert issues delete my-org/my-project/12345 --dry-run
 ### Create a metric alert rule
 
 ```bash
-# Create an organization metric alert rule
-sentry alert metrics create my-org \
+# Create an organization metric alert rule (trailing slash targets the org)
+sentry alert metrics create my-org/ \
   --name "P95 Latency" \
   --query "environment:prod" \
   --aggregate "p95(span.duration)" \

apps/cli-docs/src/fragments/commands/auth.md

@@ -57,6 +57,10 @@ For token-based auth with self-hosted:
 sentry auth --token YOUR_TOKEN --url https://sentry.example.com
 ```
 
+After a successful login, `--url` is saved as the default instance URL. A URL
+supplied only through `SENTRY_URL` is not saved, so keep it set for later
+commands.
+
 See [Self-Hosted Sentry](../self-hosted/) for details.
 
 ### Logout

apps/cli-docs/src/fragments/commands/cli.md

@@ -57,7 +57,8 @@ The CLI detects how it was installed and uses the appropriate upgrade method:
 | brew | Binary in a Homebrew Cellar (`brew install getsentry/tools/sentry`) |
 | npm | Globally installed via `npm install -g sentry` |
 | pnpm | Globally installed via `pnpm add -g sentry` |
-| bun | Globally installed via `bun install -g sentry` |
+| bun | Globally installed via `bun add -g sentry` |
+| yarn | Globally installed via `yarn global add sentry` |
 
 Nightly builds are only available as standalone binaries (via the curl install method). Switching to nightly from a package manager install will automatically migrate to a standalone binary.
 
@@ -85,6 +86,12 @@ sentry cli defaults ca-cert /path/to/ca.pem
 # Disable telemetry
 sentry cli defaults telemetry off
 
+# Stop installing agent skills on setup/upgrade (re-enable with "on")
+sentry cli defaults agent-skills off
+
+# Disable inline terminal images (kitty/sixel)
+sentry cli defaults graphics off
+
 # Clear a single default
 sentry cli defaults org --clear
 
@@ -149,7 +156,7 @@ sentry cli completion fish > ~/.config/fish/completions/sentry.fish
 # Run full setup (PATH, completions, agent skills)
 sentry cli setup
 
-# Skip agent skill installation
+# Skip agent skill installation (remembered for future upgrades)
 sentry cli setup --no-agent-skills
 
 # Skip PATH and completion modifications

apps/cli-docs/src/fragments/commands/index.md

@@ -9,6 +9,19 @@ All commands support the following global options:
 - `--log-level <level>` - Set log verbosity (`error`, `warn`, `log`, `info`, `debug`, `trace`). Overrides `SENTRY_LOG_LEVEL`
 - `--verbose` - Shorthand for `--log-level debug`
 
+## Targeting Organizations and Projects
+
+Many commands accept an optional `<org>/<project>` target, either as the first positional argument (list commands) or as a prefix of an ID (e.g. `my-org/my-project/<trace-id>`). When you omit it, the CLI auto-detects the org and project (see [Resolution Priority](../configuration/#resolution-priority)).
+
+| Target | Meaning |
+|--------|---------|
+| _(omitted)_ | Auto-detect org and project |
+| `<org>/<project>` | That project in that organization |
+| `<org>/` | The whole organization (trailing slash) |
+| `<name>` | A project named `<name>` in any accessible organization. If no project matches, commands that accept an organization use the org named `<name>` instead |
+
+When a project and an organization share the same slug, the bare form selects the project. Add the trailing slash (`my-org/`) to target the organization explicitly.
+
 ## JSON Output
 
 Most list and view commands support `--json` flag for JSON output, making it easy to integrate with other tools:

apps/cli-docs/src/fragments/commands/init.md

@@ -39,7 +39,7 @@ sentry init --features profiling,replay
 | _(omitted)_ | Auto-detect org and project |
 | `acme/` | Use org `acme`, auto-detect or create project |
 | `acme/my-app` | Use org `acme` and project `my-app` |
-| `my-app` | Search for project `my-app` across all accessible orgs |
+| `my-app` | Use existing project `my-app` from any accessible org; if none exists, use org `my-app` when one matches, otherwise create a new project named `my-app` |
 
 Path-like arguments (starting with `.`, `/`, or `~`) are always treated as the directory. The order of target and directory can be swapped — the CLI will auto-correct with a warning.
 

apps/cli-docs/src/fragments/configuration.md

@@ -61,15 +61,19 @@ If you previously used the legacy `sentry-cli` and have a `~/.sentryclirc` file,
 
 ## Persistent Defaults
 
-Use `sentry cli defaults` to set persistent defaults for organization, project, URL, and telemetry. These are stored in the CLI's local database and apply to all commands.
+Use `sentry cli defaults` to set persistent defaults for organization, project, Sentry URL, custom headers, CA certificate, telemetry, agent skill installation, and inline terminal graphics. These are stored in the CLI's local database and apply to all commands.
 
 ```bash
-sentry cli defaults org my-org           # Set default organization
-sentry cli defaults project my-project   # Set default project
-sentry cli defaults url https://...      # Set Sentry URL (self-hosted)
-sentry cli defaults telemetry off        # Disable telemetry
-sentry cli defaults                      # Show all current defaults
-sentry cli defaults org --clear          # Clear a specific default
+sentry cli defaults org my-org                # Set default organization
+sentry cli defaults project my-project        # Set default project
+sentry cli defaults url https://...           # Set Sentry URL (self-hosted)
+sentry cli defaults headers "X-IAP: token"    # Custom HTTP headers (self-hosted)
+sentry cli defaults ca-cert /path/to/ca.pem   # Trust a custom CA certificate
+sentry cli defaults telemetry off             # Disable telemetry
+sentry cli defaults agent-skills off          # Stop installing agent skills on setup/upgrade
+sentry cli defaults graphics off              # Disable inline terminal images
+sentry cli defaults                           # Show all current defaults
+sentry cli defaults org --clear               # Clear a specific default
 ```
 
 See [`sentry cli defaults`](./commands/cli/#sentry-cli-defaults) for full usage.
@@ -123,4 +127,4 @@ When installed via the install script, the CLI binary is placed in an XDG-aligne
 
 Older installs placed the binary in `~/.sentry/bin`. Running `sentry cli setup` moves an existing `~/.sentry/bin` binary into the resolved install directory (updating your `PATH` and recorded install metadata to match) and migrates any legacy `~/.sentry` config data (`cli.db`, `config.json`) into the XDG config directory. Both migrations are skipped when a binary or config already exists at the target.
 
-`sentry upgrade` runs `setup` on the new binary, so it migrates too — but conservatively, because upgrade never edits your `PATH`. A legacy `~/.sentry/bin` binary is relocated to the XDG install directory **only when that directory is already on your `PATH`**, so the moved binary stays discoverable. If the XDG directory isn't on `PATH`, upgrade leaves the binary in place (a mislocated binary that vanished from `PATH` would break the command); run `sentry cli setup` explicitly to relocate it and update `PATH`. Legacy config data is migrated on upgrade regardless.
+`sentry cli upgrade` runs `setup` on the new binary, so it migrates too — but conservatively, because upgrade never edits your `PATH`. A legacy `~/.sentry/bin` binary is relocated to the XDG install directory **only when that directory is already on your `PATH`**, so the moved binary stays discoverable. If the XDG directory isn't on `PATH`, upgrade leaves the binary in place (a mislocated binary that vanished from `PATH` would break the command); run `sentry cli setup` explicitly to relocate it and update `PATH`. Legacy config data is migrated on upgrade regardless.