fix(skill-gen): eliminate manual maps to prevent undocumented commands (#670)

## Summary

- Replaces the three manually-maintained maps (`ROUTE_TO_REFERENCE`,
`REFERENCE_TITLES`, `REFERENCE_DESCRIPTIONS`) in `generate-skill.ts`
with 1:1 route-to-file mapping
- Titles and descriptions are now derived from route metadata (`brief`),
matching the strategy used by `generate-command-docs.ts`
- Adding a new route to `app.ts` now automatically produces a
correctly-titled reference file with zero manual steps

## Motivation

PR #662 identified that `release` and `sourcemap` routes had degraded
skill documentation despite the fully automated generation pipeline. The
root cause was that `generate-skill.ts` required manual map updates that
`generate-command-docs.ts` did not — and the silent fallback (`??
route.name`) masked the problem by producing subtly wrong output that
CI's staleness check couldn't distinguish from correct output.

Rather than adding validation on top of the manual maps, this PR
eliminates them entirely so the two generation pipelines share the same
self-healing strategy: one file per visible route, metadata derived from
the route tree.

## Trade-off

Reference files go from 14 (grouped) to 18 (1:1). The 3 former groupings
were: `trace`+`span` → `traces.md`, `team`+`repo` → `teams.md`,
`cli`+`init`+`schema` → `setup.md`. Each route now gets its own file.

Closes #662

Author: BYK

docs/public/.well-known/skills/index.json

@@ -7,18 +7,22 @@
         "SKILL.md",
         "references/api.md",
         "references/auth.md",
-        "references/dashboards.md",
-        "references/events.md",
-        "references/issues.md",
-        "references/logs.md",
-        "references/organizations.md",
-        "references/projects.md",
+        "references/cli.md",
+        "references/dashboard.md",
+        "references/event.md",
+        "references/init.md",
+        "references/issue.md",
+        "references/log.md",
+        "references/org.md",
+        "references/project.md",
         "references/release.md",
-        "references/setup.md",
+        "references/repo.md",
+        "references/schema.md",
         "references/sourcemap.md",
-        "references/teams.md",
-        "references/traces.md",
-        "references/trials.md"
+        "references/span.md",
+        "references/team.md",
+        "references/trace.md",
+        "references/trial.md"
       ]
     }
   ]

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -276,7 +276,7 @@ Work with Sentry organizations
 - `sentry org list` — List organizations
 - `sentry org view <org>` — View details of an organization
 
-→ Full flags and examples: `references/organizations.md`
+→ Full flags and examples: `references/org.md`
 
 ### Project
 
@@ -287,7 +287,7 @@ Work with Sentry projects
 - `sentry project list <org/project>` — List projects
 - `sentry project view <org/project>` — View details of a project
 
-→ Full flags and examples: `references/projects.md`
+→ Full flags and examples: `references/project.md`
 
 ### Issue
 
@@ -299,25 +299,25 @@ Manage Sentry issues
 - `sentry issue plan <issue>` — Generate a solution plan using Seer AI
 - `sentry issue view <issue>` — View details of a specific issue
 
-→ Full flags and examples: `references/issues.md`
+→ Full flags and examples: `references/issue.md`
 
 ### Event
 
 View Sentry events
 
 - `sentry event view <org/project/event-id...>` — View details of a specific event
 
-→ Full flags and examples: `references/events.md`
+→ Full flags and examples: `references/event.md`
 
-### Api
+### API
 
 Make an authenticated API request
 
 - `sentry api <endpoint>` — Make an authenticated API request
 
 → Full flags and examples: `references/api.md`
 
-### Cli
+### CLI
 
 CLI-related commands
 
@@ -326,7 +326,7 @@ CLI-related commands
 - `sentry cli setup` — Configure shell integration
 - `sentry cli upgrade <version>` — Update the Sentry CLI to the latest version
 
-→ Full flags and examples: `references/setup.md`
+→ Full flags and examples: `references/cli.md`
 
 ### Dashboard
 
@@ -339,7 +339,7 @@ Manage Sentry dashboards
 - `sentry dashboard widget edit <org/project/dashboard...>` — Edit a widget in a dashboard
 - `sentry dashboard widget delete <org/project/dashboard...>` — Delete a widget from a dashboard
 
-→ Full flags and examples: `references/dashboards.md`
+→ Full flags and examples: `references/dashboard.md`
 
 ### Release
 
@@ -363,15 +363,15 @@ Work with Sentry repositories
 
 - `sentry repo list <org/project>` — List repositories
 
-→ Full flags and examples: `references/teams.md`
+→ Full flags and examples: `references/repo.md`
 
 ### Team
 
 Work with Sentry teams
 
 - `sentry team list <org/project>` — List teams
 
-→ Full flags and examples: `references/teams.md`
+→ Full flags and examples: `references/team.md`
 
 ### Log
 
@@ -380,7 +380,7 @@ View Sentry logs
 - `sentry log list <org/project-or-trace-id...>` — List logs from a project
 - `sentry log view <org/project/log-id...>` — View details of one or more log entries
 
-→ Full flags and examples: `references/logs.md`
+→ Full flags and examples: `references/log.md`
 
 ### Sourcemap
 
@@ -398,7 +398,7 @@ List and view spans in projects or traces
 - `sentry span list <org/project/trace-id...>` — List spans in a project or trace
 - `sentry span view <trace-id/span-id...>` — View details of specific spans
 
-→ Full flags and examples: `references/traces.md`
+→ Full flags and examples: `references/span.md`
 
 ### Trace
 
@@ -408,7 +408,7 @@ View distributed traces
 - `sentry trace view <org/project/trace-id...>` — View details of a specific trace
 - `sentry trace logs <org/trace-id...>` — View logs associated with a trace
 
-→ Full flags and examples: `references/traces.md`
+→ Full flags and examples: `references/trace.md`
 
 ### Trial
 
@@ -417,23 +417,23 @@ Manage product trials
 - `sentry trial list <org>` — List product trials
 - `sentry trial start <name> <org>` — Start a product trial
 
-→ Full flags and examples: `references/trials.md`
+→ Full flags and examples: `references/trial.md`
 
 ### Init
 
 Initialize Sentry in your project (experimental)
 
 - `sentry init <target> <directory>` — Initialize Sentry in your project (experimental)
 
-→ Full flags and examples: `references/setup.md`
+→ Full flags and examples: `references/init.md`
 
 ### Schema
 
 Browse the Sentry API schema
 
 - `sentry schema <resource...>` — Browse the Sentry API schema
 
-→ Full flags and examples: `references/setup.md`
+→ Full flags and examples: `references/schema.md`
 
 ## Global Options
 

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

@@ -1,13 +1,13 @@
 ---
 name: sentry-cli-api
 version: 0.25.0-dev.0
-description: Make arbitrary Sentry API requests
+description: Make an authenticated API request
 requires:
   bins: ["sentry"]
   auth: true
 ---
 
-# API Command
+# API Commands
 
 Make an authenticated API request
 

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

@@ -1,13 +1,13 @@
 ---
 name: sentry-cli-auth
 version: 0.25.0-dev.0
-description: Authenticate with Sentry via OAuth or API tokens
+description: Authenticate with Sentry
 requires:
   bins: ["sentry"]
   auth: true
 ---
 
-# Authentication Commands
+# Auth Commands
 
 Authenticate with Sentry
 

…li/skills/sentry-cli/references/setup.md …-cli/skills/sentry-cli/references/cli.mdplugins/sentry-cli/skills/sentry-cli/references/setup.md renamed to plugins/sentry-cli/skills/sentry-cli/references/cli.md plugins/sentry-cli/skills/sentry-cli/references/setup.md renamed to plugins/sentry-cli/skills/sentry-cli/references/cli.md

@@ -1,20 +1,16 @@
 ---
-name: sentry-cli-setup
+name: sentry-cli-cli
 version: 0.25.0-dev.0
-description: Configure the CLI, install integrations, and manage upgrades
+description: CLI-related commands
 requires:
   bins: ["sentry"]
   auth: true
 ---
 
-# CLI Setup Commands
+# CLI Commands
 
 CLI-related commands
 
-Initialize Sentry in your project (experimental)
-
-Browse the Sentry API schema
-
 ### `sentry cli feedback <message...>`
 
 Send feedback about the CLI
@@ -99,69 +95,4 @@ sentry cli upgrade nightly
 sentry cli upgrade stable
 ```
 
-### `sentry init <target> <directory>`
-
-Initialize Sentry in your project (experimental)
-
-**Flags:**
-- `-y, --yes - Non-interactive mode (accept defaults)`
-- `--dry-run - Preview changes without applying them`
-- `--features <value>... - Features to enable: errors,tracing,logs,replay,metrics,profiling,sourcemaps,crons,ai-monitoring,user-feedback`
-- `-t, --team <value> - Team slug to create the project under`
-
-**Examples:**
-
-```bash
-# Interactive setup
-sentry init
-
-# Non-interactive with auto-yes
-sentry init -y
-
-# Dry run to preview changes
-sentry init --dry-run
-
-# Target a subdirectory
-sentry init ./my-app
-
-# Use a specific org (auto-detect project)
-sentry init acme/
-
-# Use a specific org and project
-sentry init acme/my-app
-
-# Assign a team when creating a new project
-sentry init acme/ --team backend
-
-# Enable specific features
-sentry init --features profiling,replay
-```
-
-### `sentry schema <resource...>`
-
-Browse the Sentry API schema
-
-**Flags:**
-- `--all - Show all endpoints in a flat list`
-- `-q, --search <value> - Search endpoints by keyword`
-
-**Examples:**
-
-```bash
-# List all API resources
-sentry schema
-
-# Browse issue endpoints
-sentry schema issues
-
-# View details for a specific operation
-sentry schema issues list
-
-# Search for monitoring-related endpoints
-sentry schema --search monitor
-
-# Flat list of every endpoint
-sentry schema --all
-```
-
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

…ills/sentry-cli/references/dashboards.md …kills/sentry-cli/references/dashboard.mdplugins/sentry-cli/skills/sentry-cli/references/dashboards.md renamed to plugins/sentry-cli/skills/sentry-cli/references/dashboard.md plugins/sentry-cli/skills/sentry-cli/references/dashboards.md renamed to plugins/sentry-cli/skills/sentry-cli/references/dashboard.md

@@ -1,7 +1,7 @@
 ---
-name: sentry-cli-dashboards
+name: sentry-cli-dashboard
 version: 0.25.0-dev.0
-description: List, view, and create Sentry dashboards
+description: Manage Sentry dashboards
 requires:
   bins: ["sentry"]
   auth: true

…i/skills/sentry-cli/references/events.md …li/skills/sentry-cli/references/event.mdplugins/sentry-cli/skills/sentry-cli/references/events.md renamed to plugins/sentry-cli/skills/sentry-cli/references/event.md plugins/sentry-cli/skills/sentry-cli/references/events.md renamed to plugins/sentry-cli/skills/sentry-cli/references/event.md

@@ -1,7 +1,7 @@
 ---
-name: sentry-cli-events
+name: sentry-cli-event
 version: 0.25.0-dev.0
-description: View individual error events
+description: View Sentry events
 requires:
   bins: ["sentry"]
   auth: true

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

@@ -0,0 +1,52 @@
+---
+name: sentry-cli-init
+version: 0.25.0-dev.0
+description: Initialize Sentry in your project (experimental)
+requires:
+  bins: ["sentry"]
+  auth: true
+---
+
+# Init Commands
+
+Initialize Sentry in your project (experimental)
+
+### `sentry init <target> <directory>`
+
+Initialize Sentry in your project (experimental)
+
+**Flags:**
+- `-y, --yes - Non-interactive mode (accept defaults)`
+- `--dry-run - Preview changes without applying them`
+- `--features <value>... - Features to enable: errors,tracing,logs,replay,metrics,profiling,sourcemaps,crons,ai-monitoring,user-feedback`
+- `-t, --team <value> - Team slug to create the project under`
+
+**Examples:**
+
+```bash
+# Interactive setup
+sentry init
+
+# Non-interactive with auto-yes
+sentry init -y
+
+# Dry run to preview changes
+sentry init --dry-run
+
+# Target a subdirectory
+sentry init ./my-app
+
+# Use a specific org (auto-detect project)
+sentry init acme/
+
+# Use a specific org and project
+sentry init acme/my-app
+
+# Assign a team when creating a new project
+sentry init acme/ --team backend
+
+# Enable specific features
+sentry init --features profiling,replay
+```
+
+All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

…i/skills/sentry-cli/references/issues.md …li/skills/sentry-cli/references/issue.mdplugins/sentry-cli/skills/sentry-cli/references/issues.md renamed to plugins/sentry-cli/skills/sentry-cli/references/issue.md plugins/sentry-cli/skills/sentry-cli/references/issues.md renamed to plugins/sentry-cli/skills/sentry-cli/references/issue.md

@@ -1,7 +1,7 @@
 ---
-name: sentry-cli-issues
+name: sentry-cli-issue
 version: 0.25.0-dev.0
-description: List, view, and analyze Sentry issues with AI
+description: Manage Sentry issues
 requires:
   bins: ["sentry"]
   auth: true

…cli/skills/sentry-cli/references/logs.md …-cli/skills/sentry-cli/references/log.mdplugins/sentry-cli/skills/sentry-cli/references/logs.md renamed to plugins/sentry-cli/skills/sentry-cli/references/log.md plugins/sentry-cli/skills/sentry-cli/references/logs.md renamed to plugins/sentry-cli/skills/sentry-cli/references/log.md

@@ -1,7 +1,7 @@
 ---
-name: sentry-cli-logs
+name: sentry-cli-log
 version: 0.25.0-dev.0
-description: List and stream logs from Sentry projects
+description: View Sentry logs
 requires:
   bins: ["sentry"]
   auth: true