fix: review improvements for CLI bug fixes (CLI-FR, CLI-TM, CLI-RN)

- api: narrow control-char regex to line breaks only + add log.warn()
  (keeps rejectControlChars meaningful for NUL bytes)
- auth: add defaultCommand "status" (replaces help.ts suggestion hack)
- auth: revert help.ts enrichment and /info suggestion entry
- dashboard: fix missed x->col rename in edit.ts re-validation
- dashboard: add missing test/types/dashboard.test.ts updates
- docs: add "Intent-First Correction" UX philosophy to AGENTS.md

Author: BYK

AGENTS.md

@@ -550,6 +550,18 @@ const { sql, values } = upsert(
 );
 ```
 
+### UX Philosophy: Intent-First Correction
+
+When the user's intent is unambiguous, **do what they meant** instead of rejecting with an error. Show a `log.warn()` notice explaining what was corrected and how to do it properly next time. Only reject when intent is ambiguous or the input is genuinely dangerous (e.g., path traversal).
+
+This applies across the CLI:
+- **Input cleanup** — strip copy-paste artifacts (line breaks, indentation) and warn, rather than throwing `ValidationError`
+- **Entity type recovery** — resolve wrong-type identifiers to the correct type (see "Auto-Recovery" below)
+- **Argument order swapping** — fix swapped positional args with a stderr warning
+- **Slug/org matching** — redirect bare slugs to the most likely intent
+
+When recovery is **ambiguous or impossible**, keep the error but add entity-aware suggestions and fuzzy matches.
+
 ### Error Handling
 
 All CLI errors extend the `CliError` base class from `src/lib/errors.ts`:
@@ -1070,4 +1082,5 @@ mock.module("./some-module", () => ({
 
 <!-- lore:019cc43d-e651-7154-a88e-1309c4a2a2b6 -->
 * **Testing Stricli command func() bodies via spyOn mocking**: To unit-test a Stricli command's \`func()\` body: (1) \`const func = await cmd.loader()\`, (2) \`func.call(mockContext, flags, ...args)\` with mock \`stdout\`, \`stderr\`, \`cwd\`, \`setContext\`. (3) \`spyOn\` namespace imports to mock dependencies (e.g., \`spyOn(apiClient, 'getLogs')\`). The \`loader()\` return type union causes \`.call()\` LSP errors — these are false positives that pass \`tsc --noEmit\`. When API functions are renamed (e.g., \`getLog\` → \`getLogs\`), update both spy target name AND mock return shape (single → array). Slug normalization (\`normalizeSlug\`) replaces underscores with dashes but does NOT lowercase — test assertions must match original casing (e.g., \`'CAM-82X'\` not \`'cam-82x'\`).
+
 <!-- End lore-managed section -->

src/commands/api.ts

@@ -85,13 +85,17 @@ export function parseMethod(value: string): HttpMethod {
  * @internal Exported for testing
  */
 export function normalizeEndpoint(endpoint: string): string {
-  // Strip ASCII control characters and any adjacent whitespace before
-  // validation. Users often copy-paste multi-line URLs from docs or
-  // scripts, producing newlines and indentation (CLI-FR, 215 events).
-  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentionally stripping control chars from user input
-  const cleaned = endpoint.replace(/\s*[\x00-\x1f]+\s*/g, "").trim();
+  // Strip line breaks and surrounding indentation from copy-pasted
+  // endpoints. Users often paste multi-line URLs from docs or scripts,
+  // producing newlines and indentation (CLI-FR, 215 events).
+  // Other control characters (NUL, etc.) are left for validateEndpoint
+  // to reject — those indicate corruption, not copy-paste.
+  const cleaned = endpoint.replace(/[ \t]*[\r\n]+[ \t]*/g, "").trim();
+  if (cleaned !== endpoint) {
+    log.warn("Stripped line breaks from endpoint (copy-paste artifact)");
+  }
 
-  // Reject path traversal after cleaning
+  // Reject path traversal and remaining control characters after cleaning
   validateEndpoint(cleaned);
 
   // Remove leading slash if present (rawApiRequest handles the base URL)

src/commands/auth/index.ts

@@ -15,6 +15,7 @@ export const authRoute = buildRouteMap({
     token: tokenCommand,
     whoami: whoamiCommand,
   },
+  defaultCommand: "status",
   docs: {
     brief: "Authenticate with Sentry",
     fullDescription:

src/commands/dashboard/widget/edit.ts

@@ -364,7 +364,7 @@ export const editCommand = buildCommand({
     // because the fallback dimensions weren't known yet.
     if (replacement.layout && !existing.layout) {
       validateWidgetLayout(
-        { x: replacement.layout.x, width: replacement.layout.w },
+        { col: replacement.layout.x, width: replacement.layout.w },
         replacement.layout
       );
     }

src/commands/help.ts

@@ -10,7 +10,6 @@
 
 import type { SentryContext } from "../context.js";
 import { buildCommand } from "../lib/command.js";
-import { getCommandSuggestion } from "../lib/command-suggestions.js";
 import { OutputError } from "../lib/errors.js";
 import { CommandOutput } from "../lib/formatters/output.js";
 import {
@@ -59,17 +58,6 @@ export const helpCommand = buildCommand({
     // This ensures --json mode always gets structured output.
     const result = introspectCommand(commandPath);
     if ("error" in result) {
-      // Enrich the error with a command suggestion when the unknown token
-      // matches a known synonym (e.g., "info" → "sentry auth status").
-      // Without this, agents and scripts that run `sentry info` get a bare
-      // "command not found" dump instead of an actionable hint (CLI-TM).
-      const suggestion = getCommandSuggestion("", commandPath[0] ?? "");
-      if (suggestion) {
-        const hint = suggestion.explanation
-          ? `${suggestion.explanation} ${suggestion.command}`
-          : `Try: ${suggestion.command}`;
-        result.suggestions = [hint, ...(result.suggestions ?? [])];
-      }
       // OutputError renders through the output system but exits non-zero
       throw new OutputError(result);
     }

src/lib/command-suggestions.ts

@@ -97,15 +97,6 @@ const SUGGESTIONS: ReadonlyMap<string, CommandSuggestion> = new Map([
     },
   ],
 
-  // --- top-level synonyms (from CLI-TM telemetry, 54 events) ---
-  [
-    "/info",
-    {
-      command: "sentry auth status",
-      explanation: "For account info, use",
-    },
-  ],
-
   // --- old sentry-cli commands (~5 events) ---
   ["cli/info", { command: "sentry auth status" }],
   [

test/commands/api.test.ts

@@ -127,9 +127,9 @@ describe("normalizeEndpoint: path traversal hardening (#350)", () => {
     );
   });
 
-  test("strips control characters from endpoint", () => {
-    expect(normalizeEndpoint("organizations/\x00admin/")).toBe(
-      "organizations/admin/"
+  test("rejects control characters in endpoint", () => {
+    expect(() => normalizeEndpoint("organizations/\x00admin/")).toThrow(
+      /Invalid/
     );
   });
 
@@ -141,11 +141,18 @@ describe("normalizeEndpoint: path traversal hardening (#350)", () => {
     ).toBe("organizations/my-org/issues/?environment=Production&project=123");
   });
 
-  test("strips tabs and carriage returns from endpoint", () => {
-    expect(normalizeEndpoint("organizations/\tmy-org/\r\nissues/")).toBe(
+  test("strips carriage returns and surrounding indentation", () => {
+    expect(normalizeEndpoint("organizations/my-org/\r\n  issues/")).toBe(
       "organizations/my-org/issues/"
     );
   });
+
+  test("preserves tabs within segments (not line-break related)", () => {
+    // Tabs without adjacent line breaks are control chars — rejected
+    expect(() => normalizeEndpoint("organizations/\tmy-org/")).toThrow(
+      /Invalid/
+    );
+  });
 });
 
 describe("parseFieldKey error cases", () => {

test/lib/command-suggestions.test.ts

@@ -144,8 +144,11 @@ describe("routes with defaultCommand", () => {
     }
   });
 
-  test("route groups without view do not have defaultCommand", () => {
-    expect(routesWithDefault.has("auth")).toBe(false);
+  test("auth route group has defaultCommand (status)", () => {
+    expect(routesWithDefault.has("auth")).toBe(true);
+  });
+
+  test("route groups without defaultCommand", () => {
     expect(routesWithDefault.has("cli")).toBe(false);
     expect(routesWithDefault.has("sourcemap")).toBe(false);
     expect(routesWithDefault.has("repo")).toBe(false);

test/lib/completions.property.test.ts

@@ -182,6 +182,7 @@ describe("proposeCompletions: Stricli integration", () => {
   // potential positional arg for the default command and proposes flags
   // instead. These groups are tested separately below.
   const groupsWithDefaultCommand = new Set([
+    "auth",
     "issue",
     "event",
     "org",

test/types/dashboard.test.ts

@@ -974,15 +974,15 @@ describe("validateWidgetLayout", () => {
 
   test("accepts valid layout flags", () => {
     expect(() =>
-      validateWidgetLayout({ x: 0, y: 0, width: 3, height: 2 })
+      validateWidgetLayout({ col: 0, row: 0, width: 3, height: 2 })
     ).not.toThrow();
     expect(() =>
-      validateWidgetLayout({ x: 5, y: 10, width: 1, height: 1 })
+      validateWidgetLayout({ col: 5, row: 10, width: 1, height: 1 })
     ).not.toThrow();
   });
 
   test("accepts partial layout flags", () => {
-    expect(() => validateWidgetLayout({ x: 3 })).not.toThrow();
+    expect(() => validateWidgetLayout({ col: 3 })).not.toThrow();
     expect(() => validateWidgetLayout({ width: 6 })).not.toThrow();
     expect(() => validateWidgetLayout({ height: 4 })).not.toThrow();
   });
@@ -991,17 +991,17 @@ describe("validateWidgetLayout", () => {
     expect(() => validateWidgetLayout({})).not.toThrow();
   });
 
-  test("rejects x >= GRID_COLUMNS", () => {
-    expect(() => validateWidgetLayout({ x: 6 })).toThrow(ValidationError);
-    expect(() => validateWidgetLayout({ x: 100 })).toThrow(ValidationError);
+  test("rejects col >= GRID_COLUMNS", () => {
+    expect(() => validateWidgetLayout({ col: 6 })).toThrow(ValidationError);
+    expect(() => validateWidgetLayout({ col: 100 })).toThrow(ValidationError);
   });
 
-  test("rejects negative x", () => {
-    expect(() => validateWidgetLayout({ x: -1 })).toThrow(ValidationError);
+  test("rejects negative col", () => {
+    expect(() => validateWidgetLayout({ col: -1 })).toThrow(ValidationError);
   });
 
-  test("rejects negative y", () => {
-    expect(() => validateWidgetLayout({ y: -1 })).toThrow(ValidationError);
+  test("rejects negative row", () => {
+    expect(() => validateWidgetLayout({ row: -1 })).toThrow(ValidationError);
   });
 
   test("rejects width < 1", () => {
@@ -1018,32 +1018,32 @@ describe("validateWidgetLayout", () => {
     expect(() => validateWidgetLayout({ height: -1 })).toThrow(ValidationError);
   });
 
-  test("rejects x + width > GRID_COLUMNS", () => {
-    expect(() => validateWidgetLayout({ x: 4, width: 4 })).toThrow(
+  test("rejects col + width > GRID_COLUMNS", () => {
+    expect(() => validateWidgetLayout({ col: 4, width: 4 })).toThrow(
       ValidationError
     );
-    expect(() => validateWidgetLayout({ x: 5, width: 2 })).toThrow(
+    expect(() => validateWidgetLayout({ col: 5, width: 2 })).toThrow(
       ValidationError
     );
   });
 
-  test("allows x + width = GRID_COLUMNS (exactly fills)", () => {
-    expect(() => validateWidgetLayout({ x: 3, width: 3 })).not.toThrow();
-    expect(() => validateWidgetLayout({ x: 0, width: 6 })).not.toThrow();
+  test("allows col + width = GRID_COLUMNS (exactly fills)", () => {
+    expect(() => validateWidgetLayout({ col: 3, width: 3 })).not.toThrow();
+    expect(() => validateWidgetLayout({ col: 0, width: 6 })).not.toThrow();
   });
 
   test("cross-validates with existing layout", () => {
     const existing = { x: 4, y: 0, w: 2, h: 1 };
-    // Changing only x=5 with existing w=2 → 5+2=7 > 6
-    expect(() => validateWidgetLayout({ x: 5 }, existing)).toThrow(
+    // Changing only col=5 with existing w=2 → 5+2=7 > 6
+    expect(() => validateWidgetLayout({ col: 5 }, existing)).toThrow(
       ValidationError
     );
     // Changing only width=3 with existing x=4 → 4+3=7 > 6
     expect(() => validateWidgetLayout({ width: 3 }, existing)).toThrow(
       ValidationError
     );
-    // Valid: x=4 with existing w=2 → 4+2=6 ≤ 6
-    expect(() => validateWidgetLayout({ x: 4 }, existing)).not.toThrow();
+    // Valid: col=4 with existing w=2 → 4+2=6 ≤ 6
+    expect(() => validateWidgetLayout({ col: 4 }, existing)).not.toThrow();
   });
 });