docs(cli): Reject sentry commands in fragment code blocks

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

@@ -74,6 +74,7 @@ that fits what they target, without changing the active account:
   `sentry auth status` show it with its user when the server reports one. It
   can't be selected with `sentry auth switch`.
 
+<!-- allow-commands: shows account selection across commands, not auth usage -->
 ```bash
 # Active account is personal; this uses the work account that knows acme-corp
 sentry issue list acme-corp/

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

@@ -22,11 +22,7 @@ The DSN is resolved in priority order:
 ## Attachments
 
 `sentry event view --json` lists an event's attachment metadata. Download an
-attachment with `sentry api`:
-
-```bash
-sentry api "https://sentry.io/api/0/projects/my-org/my-project/events/EVENT_ID/attachments/ATTACHMENT_ID/?download=1" > screenshot.png
-```
+attachment with `sentry api` and the attachment's `?download=1` URL.
 
 ## Finding Event IDs
 
@@ -38,8 +34,5 @@ Event IDs can be found:
 
 ## Backward compatibility
 
-The old sentry-cli top-level command is available as a hidden alias:
-
-```bash
-sentry send-event    # same as: sentry event send
-```
+The old sentry-cli top-level command `sentry send-event` is available as a
+hidden alias for `sentry event send`.

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

@@ -13,6 +13,7 @@ All commands support the following global options:
 
 Most list and view commands support `--json` flag for JSON output, making it easy to integrate with other tools:
 
+<!-- allow-commands: global flag shown on a representative command -->
 ```bash
 sentry org list --json | jq '.[] | .slug'
 ```
@@ -21,6 +22,7 @@ sentry org list --json | jq '.[] | .slug'
 
 View commands support `-w` or `--web` flag to open the resource in your browser:
 
+<!-- allow-commands: global flag shown on a representative command -->
 ```bash
 sentry issue view PROJ-123 -w
 ```

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

@@ -39,15 +39,7 @@ Sentry.init({ spotlight: process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT ?? false });
 
 ## Browser UI
 
-Use `--open` to launch the Sentry Local UI ([local.sentry.dev](https://local.sentry.dev)) in your browser. The UI connects to the local receiver via the loopback stream endpoint and provides a visual workspace for browsing errors, traces, logs, and AI spans captured during the session.
-
-```bash
-# Start the server and open the UI
-sentry local --open
-
-# Run your app with the UI
-sentry local run --open -- npm run dev
-```
+Use `--open` with `sentry local` or `sentry local run` to launch the Sentry Local UI ([local.sentry.dev](https://local.sentry.dev)) in your browser. The UI connects to the local receiver via the loopback stream endpoint and provides a visual workspace for browsing errors, traces, logs, and AI spans captured during the session.
 
 The `--open` flag requires a loopback `--host` (localhost, 127.0.0.1, or ::1). The hosted UI reads the SSE stream without changing retained receiver data. A loopback-served viewer can clear a receiver and reset or close a scoped daemon session. Session data stays in memory for the duration of the server; nothing is sent to sentry.io unless a DSN is configured.
 
@@ -72,11 +64,8 @@ By default, incoming envelopes are pretty-printed to the terminal:
 
 Errors show the exception type, message, and top stack frame. Transactions show the operation, duration, and span count. Logs show the severity level, message, and custom attributes.
 
-Use `--filter` / `-f` to narrow the output to specific event types (repeatable):
-
-```bash
-sentry local -f error -f log    # only errors and logs
-```
+Use `--filter` / `-f` to narrow the output to specific event types. The flag is
+repeatable, so `-f error -f log` shows only errors and logs.
 
 Use `--quiet` to suppress tail output entirely if you only need the SSE stream.
 
@@ -93,30 +82,17 @@ Use `--quiet` to suppress tail output entirely if you only need the SSE stream.
 
 GenAI operations show the model name, MCP tool calls show the tool being invoked, and database queries show the system and query summary. This works automatically when your Sentry SDK is configured with AI/LLM integrations.
 
-To watch only agent activity, filter to the `ai` item type:
-
-```bash
-sentry local -f ai          # only AI/agent spans
-sentry local -f ai -f error # agent spans and errors
-```
+To watch only agent activity, filter to the `ai` item type with `-f ai`, and add
+`-f error` to keep errors alongside agent spans.
 
 ## JSON output
 
-Use `--format json` (or `-F json`) for machine-readable NDJSON output, one JSON object per envelope item:
-
-```bash
-sentry local --format json
-```
+Use `--format json` (or `-F json`) for machine-readable NDJSON output, one JSON object per envelope item.
 
 `local run` supports the same JSON, attribute, and filter options while it
 starts your app and injects the receiver URL. For an agent-friendly stream
-without SDK housekeeping envelopes, use:
-
-```bash
-sentry local run --format json \
-  --filter error --filter transaction --filter log --filter ai \
-  -- npm run dev
-```
+without SDK housekeeping envelopes, filter to `error`, `transaction`, `log`, and
+`ai` items. Each JSON line looks like this:
 
 ```json
 {"type":"transaction","timestamp":1700000001,"op":"gen_ai","label":"chat anthropic/claude-4-sonnet","duration_ms":1200,"span_count":5,"source":"server"}
@@ -142,6 +118,7 @@ local server unless you explicitly set `SENTRY_DSN`.
 
 In one terminal, start the local receiver:
 
+<!-- allow-commands: step of a multi-terminal fixture walkthrough -->
 ```bash
 sentry local serve --format json --attributes
 ```
@@ -173,6 +150,7 @@ after your foreground command exits. Sessions keep up to 500 envelopes for three
 hours after closing and subsequent ingestion. Stopping or restarting the daemon
 clears all sessions.
 
+<!-- allow-commands: session lifecycle walkthrough across local subcommands -->
 ```bash
 sentry local run --session web -- npm run dev
 sentry local serve --session worker

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

@@ -19,10 +19,6 @@ available scan accuracy.
 
 ## JSON Output
 
-Use `--json` for machine-readable output:
-
-```bash
-sentry log list --json | jq '.data[] | select(.severity == "error")'
-```
+Use `--json` for machine-readable output.
 
 In streaming mode with `--json`, each log entry is output as a separate JSON object (newline-delimited JSON), making it suitable for piping to other tools.

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

@@ -20,6 +20,7 @@ and `--account` to a single account. The stored active account never changes.
 With `--json`, each entry's `account` carries that notation as `name`, with its
 parts alongside: `email` (or `username`) and `server`.
 
+<!-- allow-commands: sample output with the ACCOUNT column -->
 ```
 $ sentry org list
 SLUG             NAME               ACCOUNT

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

@@ -5,6 +5,7 @@
 A typical CI release creates the release, associates commits, finalizes it, and
 records a deploy:
 
+<!-- allow-commands: multi-step CI release workflow -->
 ```bash
 sentry release create my-org/1.0.0 --project my-project
 sentry release set-commits my-org/1.0.0 --auto

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

@@ -37,8 +37,4 @@ common cause is a bundler that isn't emitting `.map` files:
 
 For CI steps that may run against legitimately-empty directories (e.g.,
 library-only repos, conditional release skips), pass `--allow-empty` to
-suppress the error:
-
-```bash
-sentry sourcemap upload ./dist --allow-empty
-```
+suppress the error.

packages/cli/AGENTS.md

@@ -491,6 +491,7 @@ All command docs and skill files are generated via `pnpm run generate:docs` (whi
 - **Skill files** (`plugins/sentry-cli/skills/sentry-cli/`) are **committed** (consumed by external plugin systems) and auto-committed by CI when stale.
 - **Examples belong to the command**: add them to `docs.examples` (`{ description, command }[]`, see `src/commands/agent-conversation/list.ts`). They render in `--help`, the generated docs, and the skill references. Don't hand-write an `Examples:` block in `fullDescription` or an Examples heading in a fragment; the `sentry-cli/no-examples-in-full-description` lint rule and `pnpm run check:fragments` reject both.
 - Use fragments in `apps/cli-docs/src/fragments/commands/` only for prose the command metadata can't carry: guides, permissions, caveats.
+- `pnpm run check:fragments` also rejects any shell code block in a fragment that runs a `sentry` command, whatever its heading. For a real workflow, sample output, or cross-command guide, put `<!-- allow-commands: <reason> -->` on the line directly above the block.
 - `pnpm run check:fragments` validates fragment ↔ route consistency.
 - Positional `placeholder` values must be descriptive: `"org/project/trace-id"` not `"args"`.
 

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

@@ -74,6 +74,9 @@ sentry event view abc123def456abc123def456abc12345
 
 # Open in the browser
 sentry event view abc123def456abc123def456abc12345 -w
+
+# Download an attachment listed by --json (with sentry api)
+sentry api 'https://sentry.io/api/0/projects/my-org/my-project/events/EVENT_ID/attachments/ATTACHMENT_ID/?download=1' > screenshot.png
 ```
 
 ### `sentry event list <issue>`

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

@@ -75,8 +75,17 @@ sentry local --port 9000
 # Only show errors and logs (filter out transactions)
 sentry local -f error -f log
 
+# Only show AI/agent spans
+sentry local -f ai
+
 # Suppress per-envelope tail output
 sentry local --quiet
+
+# Stream NDJSON for scripts and agents
+sentry local --format json
+
+# Start the server and open the Sentry Local UI
+sentry local --open
 ```
 
 ### `sentry local session create <name...>`
@@ -136,6 +145,12 @@ sentry local run -- npm run dev
 
 # Run a Django dev server with the local server enabled
 sentry local run -- python manage.py runserver
+
+# Run your app and open the Sentry Local UI
+sentry local run --open -- npm run dev
+
+# Stream agent-relevant NDJSON without SDK housekeeping envelopes
+sentry local run --format json -f error -f transaction -f log -f ai -- npm run dev
 ```
 
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

packages/cli/script/check-fragments.ts

@@ -9,6 +9,8 @@
  *   4. Top-level fragments (e.g., configuration.md) exist
  *   5. Fragment content covers all subcommands in a route (warnings only)
  *   6. Fragments don't contain Examples sections (examples belong in docs.examples)
+ *   7. Fragment shell code blocks don't run `sentry` commands unless marked
+ *      with `<!-- allow-commands: <reason> -->` (see fragment-commands.ts)
  *
  * Usage:
  *   tsx script/check-fragments.ts            # Warnings for missing subcommands
@@ -18,6 +20,7 @@
 import { mkdirSync, readdirSync } from "node:fs";
 import { access, readFile, writeFile } from "node:fs/promises";
 import type { RouteInfo, RouteMap } from "../src/lib/introspect.js";
+import { findFragmentCommandIssues } from "./fragment-commands.js";
 import { markdownHeadings } from "./markdown.js";
 import { DOCS_FRAGMENTS } from "./paths.js";
 
@@ -119,6 +122,10 @@ for (const file of fragmentFiles) {
       `Fragment contains an Examples section: ${FRAGMENTS_DIR}/${file} (move command examples to the command's docs.examples metadata so they appear in help, generated docs, and skills)`,
     );
   }
+
+  for (const { line, message } of findFragmentCommandIssues(content)) {
+    errors.push(`${FRAGMENTS_DIR}/${file}:${line}: ${message}`);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -283,7 +290,7 @@ for (const [routeName, route] of multiCommandRoutes) {
     const msg =
       `Fragment missing subcommand coverage: ${fragmentPath}\n` +
       `    Not documented: ${missing.join(", ")}\n` +
-      `    Hint: add a heading or code example for each (e.g., "sentry ${routeName} ${missing[0]}")`;
+      `    Hint: add docs.examples to each command, or mention it in a heading or prose (e.g., "sentry ${routeName} ${missing[0]}")`;
     if (isStrict) {
       errors.push(msg);
     } else {