feat(output): add Zod schema registration to OutputConfig for self-documenting JSON fields (#582)

## Summary

- Adds optional `schema` field to `OutputConfig<T>` accepting a Zod
schema that describes the JSON output shape
- When registered, the schema automatically enriches `--help` output and
the `--fields` flag with available field names and types
- Exposes structured `jsonFields` on `CommandInfo` for `sentry help` and
SKILL.md generation
- Creates `SentryIssueSchema` with 19 documented fields (id, shortId,
title, count, userCount, firstSeen, lastSeen, status, priority, etc.)
- Registers schemas on all 7 list commands: issue, team, repo, trace,
span, log, trial
- Updates agent guidance docs to mention available fields and warn
against unnecessary `sentry api` fallbacks

## Motivation

Agents fall back to raw `sentry api` calls when they need fields like
`count`, `userCount`, `firstSeen`, or `lastSeen` because the CLI doesn't
document what `--json` returns. This makes the JSON output
self-documenting through `--help`, `sentry help <cmd>`, and SKILL.md
field tables.

Closes #566

Author: BYK

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

@@ -22,7 +22,7 @@ The `sentry` CLI follows conventions from well-known tools — if you're familia
 
 ## Context Window Tips
 
-- Use `--fields id,title,status` on list commands to reduce output size
+- Use `--json --fields` to select specific fields and reduce output size. Run `<command> --help` to see available fields. Example: `sentry issue list --json --fields shortId,title,count,userCount,lastSeen`
 - Use `--json` when piping output between commands or processing programmatically
 - Use `--limit` to cap the number of results (default is usually 10–100)
 - Prefer `sentry issue view PROJECT-123` over listing and filtering manually
@@ -158,3 +158,4 @@ sentry dashboard widget add <dashboard> "Top Endpoints" --display table \
 - **Confusing `--query` syntax**: The `--query` flag uses Sentry search syntax (e.g., `is:unresolved`, `assigned:me`), not free text search.
 - **Not using `--web`**: View commands support `-w`/`--web` to open the resource in the browser — useful for sharing links.
 - **Fetching API schemas instead of using the CLI**: Prefer `sentry schema` to browse the API and `sentry api` to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately.
+- **Using `sentry api` when CLI commands suffice**: `sentry issue list --json` already includes `count`, `userCount`, `firstSeen`, `lastSeen`, `priority`, and other fields at the top level. Use `--fields` to select specific fields. Run `--help` to see all available fields. Only fall back to `sentry api` for data the CLI doesn't expose.

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

@@ -32,7 +32,7 @@ The `sentry` CLI follows conventions from well-known tools — if you're familia
 
 ### Context Window Tips
 
-- Use `--fields id,title,status` on list commands to reduce output size
+- Use `--json --fields` to select specific fields and reduce output size. Run `<command> --help` to see available fields. Example: `sentry issue list --json --fields shortId,title,count,userCount,lastSeen`
 - Use `--json` when piping output between commands or processing programmatically
 - Use `--limit` to cap the number of results (default is usually 10–100)
 - Prefer `sentry issue view PROJECT-123` over listing and filtering manually
@@ -168,6 +168,7 @@ sentry dashboard widget add <dashboard> "Top Endpoints" --display table \
 - **Confusing `--query` syntax**: The `--query` flag uses Sentry search syntax (e.g., `is:unresolved`, `assigned:me`), not free text search.
 - **Not using `--web`**: View commands support `-w`/`--web` to open the resource in the browser — useful for sharing links.
 - **Fetching API schemas instead of using the CLI**: Prefer `sentry schema` to browse the API and `sentry api` to make requests — the CLI handles authentication and endpoint resolution, so there's rarely a need to download OpenAPI specs separately.
+- **Using `sentry api` when CLI commands suffice**: `sentry issue list --json` already includes `count`, `userCount`, `firstSeen`, `lastSeen`, `priority`, and other fields at the top level. Use `--fields` to select specific fields. Run `--help` to see all available fields. Only fall back to `sentry api` for data the CLI doesn't expose.
 
 ## Prerequisites
 

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

@@ -24,6 +24,30 @@ List issues in a project
 - `--compact - Single-line rows for compact output (auto-detects if omitted)`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 
+**JSON Fields** (use `--json --fields` to select specific fields):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Numeric issue ID |
+| `shortId` | string | Human-readable short ID (e.g. PROJ-ABC) |
+| `title` | string | Issue title |
+| `culprit` | string | Culprit string |
+| `count` | string | Total event count |
+| `userCount` | number | Number of affected users |
+| `firstSeen` | string \| null | First occurrence (ISO 8601) |
+| `lastSeen` | string \| null | Most recent occurrence (ISO 8601) |
+| `level` | string | Severity level |
+| `status` | string | Issue status |
+| `priority` | string | Triage priority |
+| `platform` | string | Platform |
+| `permalink` | string | URL to the issue in Sentry |
+| `project` | object | Project info |
+| `metadata` | object | Issue metadata |
+| `assignedTo` | unknown \| null | Assigned user or team |
+| `substatus` | string \| null | Issue substatus |
+| `isUnhandled` | boolean | Whether the issue is unhandled |
+| `seerFixabilityScore` | number \| null | Seer AI fixability score (0-1) |
+
 **Examples:**
 
 ```bash

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

@@ -22,6 +22,17 @@ List logs from a project
 - `-t, --period <value> - Time period (e.g., "90d", "14d", "24h"). Default: 90d (project mode), 14d (trace mode)`
 - `--fresh - Bypass cache, re-detect projects, and fetch fresh data`
 
+**JSON Fields** (use `--json --fields` to select specific fields):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sentry.item_id` | string | Unique log entry ID |
+| `timestamp` | string | Log timestamp (ISO 8601) |
+| `timestamp_precise` | number | Nanosecond-precision timestamp |
+| `message` | string \| null | Log message |
+| `severity` | string \| null | Severity level (error, warning, info, debug) |
+| `trace` | string \| null | Trace ID for correlation |
+
 **Examples:**
 
 ```bash

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

@@ -22,6 +22,20 @@ List repositories
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
+**JSON Fields** (use `--json --fields` to select specific fields):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Repository ID |
+| `name` | string | Repository name |
+| `url` | string \| null | Repository URL |
+| `provider` | object | Version control provider |
+| `status` | string | Integration status |
+| `dateCreated` | string | Creation date (ISO 8601) |
+| `integrationId` | string | Integration ID |
+| `externalSlug` | string \| null | External slug (e.g. org/repo) |
+| `externalId` | string \| null | External ID |
+
 ### `sentry team list <org/project>`
 
 List teams
@@ -31,6 +45,18 @@ List teams
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
+**JSON Fields** (use `--json --fields` to select specific fields):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Team ID |
+| `slug` | string | Team slug |
+| `name` | string | Team name |
+| `dateCreated` | string | Creation date (ISO 8601) |
+| `isMember` | boolean | Whether you are a member |
+| `teamRole` | string \| null | Your role in the team |
+| `memberCount` | number | Number of members |
+
 **Examples:**
 
 ```bash

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

@@ -25,6 +25,20 @@ List spans in a project or trace
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
+**JSON Fields** (use `--json --fields` to select specific fields):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Span ID |
+| `parent_span` | string \| null | Parent span ID |
+| `span.op` | string \| null | Span operation (e.g. http.client, db) |
+| `description` | string \| null | Span description |
+| `span.duration` | number \| null | Duration (ms) |
+| `timestamp` | string | Timestamp (ISO 8601) |
+| `project` | string | Project slug |
+| `transaction` | string \| null | Transaction name |
+| `trace` | string | Trace ID |
+
 ### `sentry span view <trace-id/span-id...>`
 
 View details of specific spans
@@ -45,6 +59,17 @@ List recent traces in a project
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
+**JSON Fields** (use `--json --fields` to select specific fields):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `trace` | string | Trace ID |
+| `id` | string | Event ID |
+| `transaction` | string | Transaction name |
+| `timestamp` | string | Timestamp (ISO 8601) |
+| `transaction.duration` | number | Duration (ms) |
+| `project` | string | Project slug |
+
 ### `sentry trace view <org/project/trace-id...>`
 
 View details of a specific trace

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

@@ -15,6 +15,17 @@ Manage product trials
 
 List product trials
 
+**JSON Fields** (use `--json --fields` to select specific fields):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `category` | string | Trial category (e.g. seerUsers, seerAutofix) |
+| `startDate` | string \| null | Start date (ISO 8601) |
+| `endDate` | string \| null | End date (ISO 8601) |
+| `reasonCode` | number | Reason code |
+| `isStarted` | boolean | Whether the trial has started |
+| `lengthDays` | number \| null | Trial duration in days |
+
 ### `sentry trial start <name> <org>`
 
 Start a product trial

script/generate-skill.ts

@@ -496,6 +496,22 @@ function generateFullCommandDoc(cmd: CommandInfo): string {
     }
   }
 
+  if (cmd.jsonFields && cmd.jsonFields.length > 0) {
+    lines.push("");
+    lines.push(
+      "**JSON Fields** (use `--json --fields` to select specific fields):"
+    );
+    lines.push("");
+    lines.push("| Field | Type | Description |");
+    lines.push("|-------|------|-------------|");
+    for (const field of cmd.jsonFields) {
+      // Escape pipe characters to avoid breaking the markdown table structure
+      const safeType = field.type.replaceAll("|", "\\|");
+      const safeDesc = (field.description ?? "").replaceAll("|", "\\|");
+      lines.push(`| \`${field.name}\` | ${safeType} | ${safeDesc} |`);
+    }
+  }
+
   if (cmd.examples.length > 0) {
     lines.push("");
     lines.push("**Examples:**");

src/commands/issue/list.ts

@@ -79,10 +79,11 @@ import {
 } from "../../lib/resolve-target.js";
 import { getApiBaseUrl } from "../../lib/sentry-client.js";
 import { setOrgProjectContext } from "../../lib/telemetry.js";
-import type {
-  ProjectAliasEntry,
-  SentryIssue,
-  Writer,
+import {
+  type ProjectAliasEntry,
+  type SentryIssue,
+  SentryIssueSchema,
+  type Writer,
 } from "../../types/index.js";
 
 /** Command key for pagination cursor storage */
@@ -1502,6 +1503,7 @@ const jsonTransformIssueList = jsonTransformListResult;
 const issueListOutput: OutputConfig<IssueListResult> = {
   human: formatIssueListHuman,
   jsonTransform: jsonTransformIssueList,
+  schema: SentryIssueSchema,
 };
 
 // ---------------------------------------------------------------------------

src/commands/log/list.ts

@@ -40,6 +40,7 @@ import {
   warnIfNormalized,
 } from "../../lib/trace-target.js";
 import { getUpdateNotification } from "../../lib/version-check.js";
+import { SentryLogSchema } from "../../types/index.js";
 
 type ListFlags = {
   readonly limit: number;
@@ -598,6 +599,7 @@ export const listCommand = buildListCommand(
     output: {
       human: createLogRenderer,
       jsonTransform: jsonTransformLogOutput,
+      schema: SentryLogSchema,
     },
     parameters: {
       positional: {