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) => {
diff --git a/test/keyring.integration.test.ts b/test/keyring.integration.test.ts
index ad6f072d..25d18660 100644
--- a/test/keyring.integration.test.ts
+++ b/test/keyring.integration.test.ts
@@ -5,11 +5,31 @@ import {
   setPassword,
 } from "../src/keyring/index.ts"
 
+async function isKeyringAvailable(): Promise<boolean> {
+  if (Deno.build.os === "linux") {
+    try {
+      const cmd = new Deno.Command("secret-tool", {
+        args: ["lookup", "service", "linear-cli-probe"],
+        stdout: "null",
+        stderr: "piped",
+      })
+      const { code, stderr } = await cmd.output()
+      const err = new TextDecoder().decode(stderr)
+      if (err.includes("was not provided by any .service files")) return false
+      return code === 0 || code === 1
+    } catch {
+      return false
+    }
+  }
+  return true
+}
+
 const TEST_ACCOUNT = `linear-cli-integration-test-${Date.now()}`
 
 Deno.test({
   name: "keyring integration - set, get, and delete round-trip",
   sanitizeResources: Deno.build.os !== "windows",
+  ignore: !(await isKeyringAvailable()),
   fn: async () => {
     try {
       assertEquals(await getPassword(TEST_ACCOUNT), null)