BYK · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026 · Oct 23, 2026
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
@@ -12,6 +12,7 @@
     "packages/cli/plugins/**",
     "packages/cli/README.md",
     "packages/cli/DEVELOPMENT.md",
+    "packages/cli/CONTRIBUTING.md",
     "packages/cli/CHANGELOG.md",
     "packages/cli/AGENTS.md",
     "packages/mcp-server-mocks/src/fixtures/**",

diff --git a/apps/cli-docs/src/content/docs/agent-guidance.md b/apps/cli-docs/src/content/docs/agent-guidance.md
@@ -34,7 +34,9 @@ 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`
+<!-- GENERATED:START destructive-commands -->
+- Always confirm with the user before running destructive commands: `alert issues delete`, `alert metrics delete`, `cli uninstall`, `dashboard widget delete`, `integration delete`, `issue merge`, `issue unlink`, `project delete`, `release delete`, `trial start`
+<!-- GENERATED:END destructive-commands -->
 - 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
@@ -210,7 +212,7 @@ sentry release deploy my-org/1.0.0 production
 sentry agent-conversation list
 
 # Explicit org, last 24 hours
-sentry agent-conversation list my-org --period 24h
+sentry agent-conversation list my-org/ --period 24h
 
 # View a conversation transcript
 sentry agent-conversation view my-org/conv-123

diff --git a/apps/cli-docs/src/content/docs/agentic-usage.md b/apps/cli-docs/src/content/docs/agentic-usage.md
@@ -3,7 +3,11 @@ 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, which lets them interact with Sentry directly from your development environment. Any agent that reads skills from `~/.agents` can use the skill.
+
+<!-- GENERATED:START detected-agents -->
+The CLI detects Claude Code, Claude Cowork, Cursor, Windsurf, GitHub Copilot, Gemini CLI, OpenAI Codex, Antigravity, Goose, Amp, Augment, OpenCode, Cline, Grok, Kimi, Junie, and OpenClaw.
+<!-- GENERATED:END detected-agents -->
 
 ## Automatic Installation
 
@@ -66,7 +70,7 @@ When you ask your agent about Sentry errors or want to investigate an issue, the
 
 - "Show me the latest issues in my project" → `sentry issue list`
 - "What's the stack trace for ISSUE-123?" → `sentry issue view ISSUE-123`
-- "List all projects in my organization" → `sentry project list my-org`
+- "List all projects in my organization" → `sentry project list my-org/`
 - "What API endpoints exist for releases?" → `sentry schema releases`
 - "How do I set up source maps for Next.js?" → `sentry docs "source maps Next.js"`
 - "What is Sentry's status right now?" → `sentry status`
@@ -79,4 +83,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, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, Goose, Amp, Augment, OpenCode, Cline, Grok, Kimi, Junie, OpenClaw, or any agent that reads from `~/.agents`)
+- An AI coding agent that supports the skills system, such as one of the agents listed at the top of this page or any agent that reads from `~/.agents`
diff --git a/apps/cli-docs/src/content/docs/contributing.md b/apps/cli-docs/src/content/docs/contributing.md
@@ -27,7 +27,7 @@ pnpm install
 cd packages/cli
 
 # Run CLI in development mode
-pnpm run cli -- --help
+pnpm run cli --help
 
 # Run tests
 pnpm run test

diff --git a/apps/cli-docs/src/content/docs/getting-started.mdx b/apps/cli-docs/src/content/docs/getting-started.mdx
@@ -61,6 +61,9 @@ Set `SENTRY_INIT=1` to run [`sentry init`](../commands/init/) right after instal
 curl https://cli.sentry.dev/install -fsS | SENTRY_INIT=1 bash
 ```
 
+The installer reports its own errors to Sentry. Set `SENTRY_CLI_NO_TELEMETRY=1`
+to turn this off; the CLI honors the same variable.
+
 ### Windows (PowerShell)
 
 On Windows, install the latest stable release from PowerShell:

diff --git a/apps/cli-docs/src/fragments/commands/index.md b/apps/cli-docs/src/fragments/commands/index.md
@@ -9,6 +9,20 @@ 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 take an optional `<org>/<project>` target as their first positional argument, or as a prefix of an ID (e.g. `my-org/my-project/<trace-id>`).
+
+<!-- GENERATED:START target-syntax -->
+| Target | Meaning |
+|--------|---------|
+| _(omitted)_ | Auto-detect the org and project from config, DSNs, or the directory name |
+| `<org>/<project>` | That project in that organization |
+| `<org>/<project>,<project>` | Several projects in the same organization (commands that accept several projects) |
+| `<org>/` | The whole organization |
+| `<name>` | A project named `<name>` in any accessible organization. If no project matches, commands that accept an organization use the organization named `<name>`. When both exist, the project wins: add the trailing slash (`<name>/`) to select the organization |
+<!-- GENERATED:END target-syntax -->
+
 ## JSON Output
 
 Most list and view commands support `--json` flag for JSON output, making it easy to integrate with other tools:

diff --git a/apps/cli-docs/src/fragments/commands/init.md b/apps/cli-docs/src/fragments/commands/init.md
@@ -13,7 +13,7 @@ In organization, team, and monorepo app selectors, type to filter the loaded cho
 | _(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 the existing project `my-app` from any accessible org. If there is none, use org `my-app` when one exists; 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.
 

diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md
@@ -39,7 +39,7 @@ Before working on this codebase, read the Cursor rules:
 # Development
 pnpm install                             # Install dependencies (from repo root)
 pnpm run dev                             # Run CLI in dev mode
-pnpm run cli -- <args>                   # Run the CLI with arguments
+pnpm run cli <args>                      # Run the CLI with arguments
 
 # Build
 pnpm run build                           # Build for current platform
@@ -253,8 +253,9 @@ one of these types and never reads `.resolved`.
 
 Resolvers need no command name: they read it from `this.commandPrefix`, which
 Stricli's `forCommand` and the SDK invoker set (test mock contexts set it
-too). In a `buildDeleteCommand` command, the target refuses to auto-detect, so
-delete commands don't call `requireExplicitTarget` for it.
+too). In a destructive command (`buildDeleteCommand`, or `buildCommand` with
+`destructive: true`), the target refuses to auto-detect, so those commands
+don't call `requireExplicitTarget` for it.
 
 Both steps are lazy (`lazyPositional` in `src/lib/positional-parse.ts`): the
 parse runs on the first `parsed` read and the resolver on the first

diff --git a/packages/cli/CONTRIBUTING.md b/packages/cli/CONTRIBUTING.md
@@ -16,13 +16,17 @@ sentry project list [org] [--limit N] [--json]
 sentry issue list [<org>/<project>] [--json]
 ```
 
-**Target syntax**:
-
-- `<org>/<project>` - Explicit organization and project (e.g., `my-org/frontend`)
-- `<org>/<project>,<project>` - Several projects in the same org (e.g., `my-org/web,api`)
-- `<org>/` - All projects in the specified organization
-- `<project>` - Search for project by name across all accessible organizations
-- _(omit)_ - Auto-detect from DSN or config
+**Target syntax** (generated from `src/lib/target-syntax.ts`):
+
+<!-- GENERATED:START target-syntax -->
+| Target | Meaning |
+|--------|---------|
+| _(omitted)_ | Auto-detect the org and project from config, DSNs, or the directory name |
+| `<org>/<project>` | That project in that organization |
+| `<org>/<project>,<project>` | Several projects in the same organization (commands that accept several projects) |
+| `<org>/` | The whole organization |
+| `<name>` | A project named `<name>` in any accessible organization. If no project matches, commands that accept an organization use the organization named `<name>`. When both exist, the project wins: add the trailing slash (`<name>/`) to select the organization |
+<!-- GENERATED:END target-syntax -->
 
 **Rationale**: Positional arguments follow `gh` CLI conventions and are more concise than flags.
 

diff --git a/packages/cli/DEVELOPMENT.md b/packages/cli/DEVELOPMENT.md
@@ -31,15 +31,15 @@ Dev mode (`pnpm run cli`) falls back to the CLI's public sentry.io client ID whe
 `pnpm run cli` loads `.env.local` automatically when it exists:
 
 ```bash
-pnpm run cli -- auth login
+pnpm run cli auth login
 ```
 
 ## Testing the Device Flow
 
 1. Run the CLI login command:
 
 ```bash
-pnpm run cli -- auth login
+pnpm run cli auth login
 ```
 
 2. You'll see output like:

diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -45,6 +45,8 @@ bun add -g sentry
 
 > The npm/pnpm/yarn packages require Node.js 20+. On Node.js 22.15+ the CLI uses the built-in `node:sqlite`; on Node.js 20–22.14 it transparently falls back to a bundled WASM SQLite driver.
 
+Homebrew and package manager installs don't add agent skills (package managers also skip shell completions). Run `sentry cli setup` once afterwards; see the [installation guide](https://cli.sentry.dev/getting-started/).
+
 ### Run Without Installing
 
 ```bash
@@ -149,11 +151,11 @@ cd packages/cli
 ### Running Locally
 
 ```bash
-# Run CLI in development mode
-pnpm run cli -- --help
+# Run CLI in development mode (generates missing build-time files on first run)
+pnpm run cli --help
 
-# With environment variables (create .env.local first, see DEVELOPMENT.md)
-pnpm run cli -- --help
+# Loads packages/cli/.env.local automatically when present (see DEVELOPMENT.md)
+pnpm run cli auth status
 ```
 
 ### Scripts

diff --git a/packages/cli/install b/packages/cli/install
@@ -90,6 +90,7 @@ Environment Variables:
     SENTRY_INSTALL_DIR      Override the installation directory
     SENTRY_VERSION          Install a specific version (e.g., 0.42.2, nightly)
     SENTRY_INIT             Set to 1 to run \`sentry init\` after installing
+    SENTRY_CLI_NO_TELEMETRY Set to 1 to disable installer error reporting
 
 Examples:
     curl -fsSL https://cli.sentry.dev/install | bash

diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -56,8 +56,8 @@
   },
   "scripts": {
     "tsx": "tsx --env-file-if-exists=.env.local --import ./script/require-shim.mjs",
-    "cli": "tsx --env-file-if-exists=.env.local --import ./script/require-shim.mjs src/bin.ts",
-    "dev": "pnpm run generate:schema && pnpm run generate:docs && pnpm run generate:sdk && tsx --import ./script/require-shim.mjs src/bin.ts",
+    "cli": "node script/ensure-generated.mjs && tsx --env-file-if-exists=.env.local --import ./script/require-shim.mjs --import ./script/strip-arg-separator.mjs src/bin.ts",
+    "dev": "pnpm run generate:schema && pnpm run generate:docs && pnpm run generate:sdk && tsx --import ./script/require-shim.mjs --import ./script/strip-arg-separator.mjs src/bin.ts",
     "build": "pnpm --filter @sentry/mcp-core run build && pnpm --filter @sentry/mcp-server run build && pnpm run generate:schema && pnpm run generate:docs && pnpm run generate:sdk && pnpm tsx script/build.ts --single",
     "build:all": "pnpm --filter @sentry/mcp-core run build && pnpm --filter @sentry/mcp-server run build && pnpm run generate:schema && pnpm run generate:docs && pnpm run generate:sdk && pnpm tsx script/build.ts",
     "bundle": "pnpm --filter @sentry/mcp-core run build && pnpm --filter @sentry/mcp-server run build && pnpm run generate:schema && pnpm run generate:docs && pnpm run generate:sdk && pnpm tsx script/bundle.ts",
@@ -72,7 +72,7 @@
     "generate:sdk": "pnpm tsx script/generate-sdk.ts",
     "generate:skill": "pnpm tsx script/generate-skill.ts",
     "generate:banner": "pnpm tsx script/generate-banner-sixel.ts",
-    "generate:docs": "pnpm run generate:banner && pnpm run generate:completions && pnpm run generate:command-docs && pnpm run generate:skill && pnpm run generate:docs-sections",
+    "generate:docs": "node script/ensure-generated.mjs schema && pnpm run generate:banner && pnpm run generate:completions && pnpm run generate:command-docs && pnpm run generate:docs-sections && pnpm run generate:skill",
     "generate:completions": "pnpm tsx script/generate-completion-targets.ts",
     "generate:docs-sections": "pnpm tsx script/generate-docs-sections.ts",
     "generate:schema": "pnpm tsx script/generate-api-schema.ts",
@@ -89,7 +89,10 @@
     "check:docs-sections": "pnpm tsx script/generate-docs-sections.ts --check",
     "check:env-coverage": "pnpm tsx script/check-env-coverage.ts",
     "check:stale-refs": "pnpm tsx script/check-stale-references.ts",
-    "ci:policy": "pnpm run check:patches && pnpm run check:deps && pnpm run check:errors && pnpm run check:fragments && pnpm run check:docs-sections && pnpm run check:env-coverage && pnpm run check:stale-refs"
+    "check:doc-examples": "pnpm tsx script/check-doc-examples.ts",
+    "check:installer-docs": "pnpm tsx script/check-installer-docs.ts",
+    "check:destructive": "pnpm tsx script/check-destructive-commands.ts",
+    "ci:policy": "pnpm run check:patches && pnpm run check:deps && pnpm run check:errors && pnpm run check:fragments && pnpm run check:docs-sections && pnpm run check:env-coverage && pnpm run check:stale-refs && pnpm run check:doc-examples && pnpm run check:installer-docs && pnpm run check:destructive"
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.39.0",

diff --git a/packages/cli/plugins/README.md b/packages/cli/plugins/README.md
@@ -22,7 +22,8 @@ npx @sentry/dotagents add https://cli.sentry.dev sentry-cli
 
 ### Cursor
 
-Skills are automatically available in `.cursor/skills/` for Cursor users.
+`packages/cli/.cursor/skills/sentry-cli/` symlinks to the skill files, so
+Cursor picks them up when you open this repository.
 
 ### Other Agents
 
@@ -48,25 +49,21 @@ The skill will guide the assistant to provide accurate CLI commands.
 
 ## Repository Structure
 
+<!-- GENERATED:START skill-layout -->
 ```
-cli/                              # Repository root
-├── .claude-plugin/
-│   └── marketplace.json          # Marketplace manifest
-├── .cursor/
-│   └── skills/
-│       └── sentry-cli/
-│           └── SKILL.md          # Symlink to plugins location
-├── plugins/
-│   ├── README.md                 # This file
-│   └── sentry-cli/
-│       ├── .claude-plugin/
-│       │   └── plugin.json       # Plugin manifest
-│       └── skills/
-│           └── sentry-cli/
-│               └── SKILL.md      # CLI usage skill (auto-generated)
-└── script/
-    └── generate-skill.ts         # Generates SKILL.md from CLI commands
+packages/cli/.claude-plugin/marketplace.json                  # Marketplace manifest
+packages/cli/.cursor/skills/sentry-cli/SKILL.md               # Symlink to the plugin skill
+packages/cli/.cursor/skills/sentry-cli/references             # Symlink to the plugin references
+packages/cli/plugins/README.md                                # This file
+packages/cli/plugins/sentry-cli/.claude-plugin/plugin.json    # Plugin manifest
+packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md    # CLI usage skill (generated)
+packages/cli/plugins/sentry-cli/skills/sentry-cli/references  # One file per command group (generated)
+packages/cli/script/generate-skill.ts                         # Generates SKILL.md and references/
 ```
+<!-- GENERATED:END skill-layout -->
+
+The docs site also serves these files, plus a generated `index.json` discovery
+manifest, from `apps/cli-docs/public/.well-known/skills/`.
 
 ## Updating SKILL.md
 

diff --git a/packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md b/packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md
@@ -46,7 +46,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: `alert issues delete`, `alert metrics delete`, `cli uninstall`, `dashboard widget delete`, `integration delete`, `issue merge`, `issue unlink`, `project delete`, `release delete`, `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
@@ -222,7 +222,7 @@ sentry release deploy my-org/1.0.0 production
 sentry agent-conversation list
 
 # Explicit org, last 24 hours
-sentry agent-conversation list my-org --period 24h
+sentry agent-conversation list my-org/ --period 24h
 
 # View a conversation transcript
 sentry agent-conversation view my-org/conv-123

diff --git a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/cli.md b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/cli.md
@@ -186,7 +186,7 @@ sentry cli setup --no-agent-skills
 Uninstall Sentry CLI
 
 **Flags:**
-- `--keep-config - Keep the config directory (~/.sentry) and auth tokens`
+- `--keep-config - Keep the config directory (default ~/.config/sentry) and auth tokens`
 - `-y, --yes - Skip confirmation prompt`
 - `-f, --force - Force the operation without confirmation`
 - `-n, --dry-run - Show what would happen without making changes`

diff --git a/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md b/packages/cli/plugins/sentry-cli/skills/sentry-cli/references/dashboard.md
@@ -230,13 +230,13 @@ sentry dashboard revisions 'Frontend Performance'
 sentry dashboard revisions 12345
 
 # Pass the organization explicitly
-sentry dashboard revisions my-org 12345
+sentry dashboard revisions my-org/ 12345
 
 # Fetch the next page
-sentry dashboard revisions my-org 12345 -c next
+sentry dashboard revisions my-org/ 12345 -c next
 
 # Output as JSON
-sentry dashboard revisions my-org 12345 --json
+sentry dashboard revisions my-org/ 12345 --json
 ```
 
 ### `sentry dashboard restore <org/dashboard...>`
@@ -256,7 +256,7 @@ sentry dashboard restore 'Frontend Performance' --revision 3
 sentry dashboard restore 12345 --revision 42
 
 # Pass the organization explicitly
-sentry dashboard restore my-org 12345 --revision 42
+sentry dashboard restore my-org/ 12345 --revision 42
 
 # Output the restored dashboard as JSON
 sentry dashboard restore 12345 --revision 42 --json