diff --git a/AGENTS.md b/AGENTS.md
index 879db829..7bbe9ace 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,6 +28,11 @@
 - wrap command actions in try-catch with `handleError(error, "Failed to <action>")`
 - errors display clean messages to stderr with ✗ prefix, stack traces only shown when `LINEAR_DEBUG=1`
 
+## cli flags
+
+- never use the same short flag alias (e.g. `-w`) on both a global option and a command-level option — cliffy resolves global options first, so the command-level alias will be shadowed
+- before adding a short flag, grep the codebase for that letter to ensure it's not already in use at a conflicting scope
+
 ## tests
 
 - tests on commands should mirror the directory structure of the src, e.g.
diff --git a/docs/authentication.md b/docs/authentication.md
index 3ce82f2a..c5869a7d 100644
--- a/docs/authentication.md
+++ b/docs/authentication.md
@@ -5,7 +5,7 @@ the CLI supports multiple authentication methods with the following precedence:
 1. `--api-key` flag (explicit key for single command)
 2. `LINEAR_API_KEY` environment variable
 3. `api_key` in project `.linear.toml` config
-4. `--workspace` / `-w` flag → stored credentials lookup
+4. `--workspace` flag → stored credentials lookup
 5. project's `workspace` config → stored credentials lookup
 6. default workspace from stored credentials
 
@@ -61,9 +61,9 @@ the `*` indicates the default workspace.
 # set a new default
 linear auth default side-project
 
-# or use -w flag for a single command
-linear -w side-project issue list
-linear -w acme issue create --title "Bug fix"
+# or use --workspace flag for a single command
+linear --workspace side-project issue list
+linear --workspace acme issue create --title "Bug fix"
 ```
 
 ### credentials file format
diff --git a/src/main.ts b/src/main.ts
index ecb9d13c..2167f24d 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -31,7 +31,7 @@ Environment Variables:
   LINEAR_DEBUG=1    Show full error details including stack traces`,
   )
   .globalOption(
-    "-w, --workspace <slug:string>",
+    "--workspace <slug:string>",
     "Target workspace (uses credentials)",
   )
   .globalAction((options) => {