fix(help): document target patterns and trailing-slash significance (#267)

Renames the positional placeholder from `<target>` to `<org/project>` so the
usage line is self-documenting. Adds a prose explanation of trailing-slash
semantics to the fullDescription of every command that uses parseOrgProjectArg,
and improves the --cursor rejection error in dispatchOrgScopedList to include a
contextual suggestion when a bare slug was given.

Author: BYK

src/commands/issue/list.ts

@@ -657,11 +657,15 @@ export const listCommand = buildCommand({
     brief: "List issues in a project",
     fullDescription:
       "List issues from Sentry projects.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry issue list               # auto-detect from DSN or config\n" +
       "  sentry issue list <org>/<proj>  # explicit org and project\n" +
-      "  sentry issue list <org>/        # all projects in org\n" +
+      "  sentry issue list <org>/        # all projects in org (trailing / required)\n" +
       "  sentry issue list <project>     # find project across all orgs\n\n" +
+      "The trailing slash on <org>/ is significant — without it, the argument\n" +
+      "is treated as a project name search (e.g., 'sentry' searches for a\n" +
+      "project named 'sentry', while 'sentry/' lists all projects in the\n" +
+      "'sentry' org).\n\n" +
       "In monorepos with multiple Sentry projects, shows issues from all detected projects.",
   },
   parameters: {

src/commands/log/list.ts

@@ -232,10 +232,12 @@ export const listCommand = buildCommand({
     brief: "List logs from a project",
     fullDescription:
       "List and stream logs from Sentry projects.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry log list               # auto-detect from DSN or config\n" +
       "  sentry log list <org>/<proj>  # explicit org and project\n" +
       "  sentry log list <project>     # find project across all orgs\n\n" +
+      "A bare name (no slash) is treated as a project search. Use <org>/<proj>\n" +
+      "for an explicit target.\n\n" +
       "Examples:\n" +
       "  sentry log list                    # List last 100 logs\n" +
       "  sentry log list -f                 # Stream logs (2s poll interval)\n" +
@@ -248,8 +250,8 @@ export const listCommand = buildCommand({
       kind: "tuple",
       parameters: [
         {
-          placeholder: "target",
-          brief: "Target: <org>/<project> or <project>",
+          placeholder: "org/project",
+          brief: "<org>/<project> or <project> (search)",
           parse: String,
           optional: true,
         },

src/commands/project/list.ts

@@ -607,13 +607,17 @@ export const listCommand = buildCommand({
     brief: "List projects",
     fullDescription:
       "List projects in an organization.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry project list                # auto-detect from DSN or config\n" +
-      "  sentry project list <org>/         # list all projects in org (paginated)\n" +
+      "  sentry project list <org>/         # all projects in org (paginated)\n" +
       "  sentry project list <org>/<proj>   # show specific project\n" +
       "  sentry project list <project>      # find project across all orgs\n\n" +
+      "The trailing slash on <org>/ is significant — without it, the argument\n" +
+      "is treated as a project name search (e.g., 'sentry' searches for a\n" +
+      "project named 'sentry', while 'sentry/' lists all projects in the\n" +
+      "'sentry' org). Cursor pagination (--cursor) requires the <org>/ form.\n\n" +
       "Pagination:\n" +
-      "  sentry project list <org>/ -c last  # continue from last page\n" +
+      "  sentry project list <org>/ -c last      # continue from last page\n" +
       "  sentry project list <org>/ -c <cursor>  # resume at specific cursor\n\n" +
       "Filtering and output:\n" +
       "  sentry project list --platform javascript  # filter by platform\n" +

src/commands/project/view.ts

@@ -201,19 +201,21 @@ export const viewCommand = buildCommand({
     brief: "View details of a project",
     fullDescription:
       "View detailed information about Sentry projects.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry project view                       # auto-detect from DSN or config\n" +
       "  sentry project view <org>/<project>       # explicit org and project\n" +
       "  sentry project view <project>             # find project across all orgs\n\n" +
+      "A bare name (no slash) is treated as a project search. Use <org>/<project>\n" +
+      "for an explicit target.\n\n" +
       "In monorepos with multiple Sentry projects, shows details for all detected projects.",
   },
   parameters: {
     positional: {
       kind: "tuple",
       parameters: [
         {
-          placeholder: "target",
-          brief: "Target: <org>/<project>, <project>, or omit for auto-detect",
+          placeholder: "org/project",
+          brief: "<org>/<project>, <project> (search), or omit for auto-detect",
           parse: String,
           optional: true,
         },

src/commands/trace/list.ts

@@ -67,10 +67,12 @@ export const listCommand = buildCommand({
     brief: "List recent traces in a project",
     fullDescription:
       "List recent traces from Sentry projects.\n\n" +
-      "Target specification:\n" +
+      "Target patterns:\n" +
       "  sentry trace list               # auto-detect from DSN or config\n" +
       "  sentry trace list <org>/<proj>  # explicit org and project\n" +
       "  sentry trace list <project>     # find project across all orgs\n\n" +
+      "A bare name (no slash) is treated as a project search. Use <org>/<proj>\n" +
+      "for an explicit target.\n\n" +
       "Examples:\n" +
       "  sentry trace list                     # List last 10 traces\n" +
       "  sentry trace list --limit 50          # Show more traces\n" +
@@ -82,8 +84,8 @@ export const listCommand = buildCommand({
       kind: "tuple",
       parameters: [
         {
-          placeholder: "target",
-          brief: "Target: <org>/<project> or <project>",
+          placeholder: "org/project",
+          brief: "<org>/<project> or <project> (search)",
           parse: String,
           optional: true,
         },

src/lib/list-command.ts

@@ -24,17 +24,17 @@ import { dispatchOrgScopedList, type OrgListConfig } from "./org-list.js";
 // ---------------------------------------------------------------------------
 
 /**
- * Positional `target` parameter shared by all list commands.
+ * Positional `org/project` parameter shared by all list commands.
  *
- * Accepts `<org>/`, `<org>/<project>`, or bare `<org>` / `<project>`.
+ * Accepts `<org>/`, `<org>/<project>`, or bare `<project>` (search).
  * Marked optional so the command falls back to auto-detection when omitted.
  */
 export const LIST_TARGET_POSITIONAL = {
   kind: "tuple" as const,
   parameters: [
     {
-      placeholder: "target",
-      brief: "Target: <org>/, <org>/<project>, or <org>",
+      placeholder: "org/project",
+      brief: "<org>/ (all projects), <org>/<project>, or <project> (search)",
       parse: String,
       optional: true as const,
     },

src/lib/org-list.ts

@@ -739,10 +739,15 @@ export async function dispatchOrgScopedList<TEntity, TWithOrg>(
 
   // Cursor pagination is only supported in org-all mode
   if (flags.cursor && parsed.type !== "org-all") {
+    const hint =
+      parsed.type === "project-search"
+        ? `\n\nDid you mean '${config.commandPrefix} ${parsed.projectSlug}/'? ` +
+          "A bare name searches for a project — add a trailing slash to list an org's projects."
+        : "";
     throw new ValidationError(
-      `The --cursor flag is only supported when listing ${config.entityPlural} for a specific organization ` +
-        `(e.g., ${config.commandPrefix} <org>/). ` +
-        `Use '${config.commandPrefix} <org>/' for paginated results.`,
+      "The --cursor flag requires the <org>/ pattern " +
+        `(e.g., ${config.commandPrefix} my-org/).` +
+        hint,
       "cursor"
     );
   }