docs: documentation audit — fix license, env var gaps, skill install claims, and missing examples

.craft.yml

@@ -38,7 +38,7 @@ targets:
         desc "Sentry command-line tool for error monitoring and debugging"
         homepage "https://cli.sentry.dev"
         version "{{version}}"
-        license "FSL-1.1-MIT"
+        license "FSL-1.1-Apache-2.0"
 
         if OS.mac?
           if Hardware::CPU.arm?

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

@@ -7,7 +7,9 @@ AI coding agents like Claude Code — and any agent that reads skills from `~/.a
 
 ## 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.
+When you install the CLI via `curl` or Homebrew, `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.
+
+If you installed via a package manager (`npm`, `pnpm`, `bun`, `yarn`), run `sentry cli setup` once to install the skills — there is no automatic postinstall hook.
 
 To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli setup`.
 

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

@@ -211,11 +211,11 @@ Calls should be sequential (awaited one at a time).
 | **Output** | Parsed object (zero-copy) | String (needs JSON.parse) |
 | **Errors** | `SentryError` with typed fields | Exit code + stderr string |
 | **Auth** | `token` option or env vars | Env vars only |
-| **Node.js** | >=22 required | Any version |
+| **Node.js** | >=22.15 required | Any version |
 
 ## Requirements
 
-- **Node.js >= 22** (required for `node:sqlite`)
+- **Node.js >= 22.15** (required for `node:sqlite`)
 
 ## Streaming Commands
 

docs/src/fragments/commands/proguard.md

@@ -2,6 +2,24 @@
 
 ## Examples
 
+### Upload
+
+```bash
+# Upload a ProGuard/R8 mapping file (org/project auto-detected)
+sentry proguard upload ./app/build/outputs/mapping/release/mapping.txt
+
+# Upload multiple mapping files
+sentry proguard upload mapping-app.txt mapping-lib.txt
+
+# Upload with a specific UUID (overrides the computed UUID)
+sentry proguard upload --uuid abcdef01-2345-6789-abcd-ef0123456789 mapping.txt
+
+# Validate without uploading
+sentry proguard upload --no-upload mapping.txt
+```
+
+### UUID
+
 ```bash
 # Compute the UUID for a ProGuard/R8 mapping file
 sentry proguard uuid ./app/build/outputs/mapping/release/mapping.txt
@@ -17,3 +35,5 @@ sentry proguard uuid mapping.txt --json
   Sentry uses to associate a mapping with obfuscated Android stack traces.
 - This matches the UUID computed by the legacy `sentry-cli proguard uuid`
   command byte-for-byte.
+- Upload uses the Sentry chunk-upload protocol (DIF). Each mapping is
+  bundled as `proguard/<uuid>.txt`.

plugins/README.md

@@ -61,19 +61,27 @@ cli/                              # Repository root
 ├── .cursor/
 │   └── skills/
 │       └── sentry-cli/
-│           └── SKILL.md          # Symlink to plugins location
+│           ├── SKILL.md          # Symlink → plugins/.../SKILL.md
+│           └── references/       # Copies of per-command reference files
+│               ├── issue.md
+│               └── ...           # One .md per visible route (26 total)
 ├── plugins/
 │   ├── README.md                 # This file
 │   └── sentry-cli/
 │       ├── .claude-plugin/
 │       │   └── plugin.json       # Plugin manifest
 │       └── skills/
 │           └── sentry-cli/
-│               └── SKILL.md      # CLI usage skill (auto-generated)
+│               ├── SKILL.md      # CLI usage skill (auto-generated)
+│               └── references/   # Per-command reference files (canonical)
+│                   ├── issue.md
+│                   └── ...
 └── script/
-    └── generate-skill.ts         # Generates SKILL.md from CLI commands
+    └── generate-skill.ts         # Generates SKILL.md + references from CLI commands
 ```
 
+`SKILL.md` under `.cursor/skills/` is a symlink to the canonical `plugins/` location. The `references/` files are copies kept in sync by CI — the canonical source is `plugins/sentry-cli/skills/sentry-cli/references/`.
+
 ## Updating SKILL.md
 
 The SKILL.md file is **auto-generated** from the CLI's command definitions. Do not edit it manually.

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

@@ -20,6 +20,22 @@ Upload ProGuard/R8 mapping files to Sentry
 - `--no-upload - Compute and print UUIDs without uploading (dry-run)`
 - `--require-one - Require at least one mapping file (error if none provided)`
 
+**Examples:**
+
+```bash
+# Upload a ProGuard/R8 mapping file (org/project auto-detected)
+sentry proguard upload ./app/build/outputs/mapping/release/mapping.txt
+
+# Upload multiple mapping files
+sentry proguard upload mapping-app.txt mapping-lib.txt
+
+# Upload with a specific UUID (overrides the computed UUID)
+sentry proguard upload --uuid abcdef01-2345-6789-abcd-ef0123456789 mapping.txt
+
+# Validate without uploading
+sentry proguard upload --no-upload mapping.txt
+```
+
 ### `sentry proguard uuid <path>`
 
 Compute the UUID for a ProGuard mapping file