From 5797c008823e79a16801cf09d084c0df9495365c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 3 Dec 2025 16:26:21 +0000
Subject: [PATCH] docs: clarify transport vs credentials; show engine+source in
 whoami

---
 README.md    | 17 +++++++++++------
 src/index.ts | 16 ++++++++++++++++
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index ef5d5cb..faed811 100644
--- a/README.md
+++ b/README.md
@@ -41,8 +41,11 @@ bird tweet "hello from bird"
 bird replies https://x.com/user/status/1234567890123456789
 ```
 
-Global engine switch:
-- `--engine graphql|sweetistics|auto` (default `auto`). `auto` uses Sweetistics when an API key is provided, otherwise falls back to direct GraphQL. `sweetistics` requires `--sweetistics-api-key` (or env) and uses Sweetistics for all commands. `graphql` forces direct Twitter cookies even if an API key is present.
+Transport (engine) selection:
+- `--engine graphql|sweetistics|auto` (default `auto`).
+  - `sweetistics`: use Sweetistics API key, no browser cookies needed.
+  - `graphql`: use Twitter/X GraphQL with cookies (Chrome/Firefox/env/flags).
+  - `auto`: Sweetistics if an API key is available, otherwise GraphQL.
 
 You can set persistent defaults via config files (JSON5):
 
@@ -146,12 +149,14 @@ bird check
    - Requires Chrome to be logged into x.com
    - May prompt for keychain access on first run
 
-### Browser cookie sources (macOS)
+### Credential sources (macOS)
 
-- **Chrome (default)**: reads `~/Library/Application Support/Google/Chrome/<Profile>/Cookies` (WAL/SHM copied too). Select with `--chrome-profile <name>`; defaults to `Default` or whatever you set in config.
-- **Firefox**: reads `~/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite`. Select with `--firefox-profile <name>`; defaults to `*.default-release` if present. Use this when Chrome isn’t logged in.
+Used only when transport resolves to **graphql**:
+- **Chrome (default)**: `~/Library/Application Support/Google/Chrome/<Profile>/Cookies` (WAL/SHM copied too). `--chrome-profile <name>`.
+- **Firefox**: `~/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite`. `--firefox-profile <name>` (defaults to `*.default-release` if present).
+- **Env/flags** always override browser cookies.
 
-Precedence still holds: CLI flags > env vars > project config > global config. So a one-off `--firefox-profile default-release` overrides any config defaults.
+Precedence: CLI flags > env vars > project config > global config. Transport is chosen first; then, if transport is GraphQL, cookie source is chosen.
 
 ### Posting via Sweetistics (API key)
 
diff --git a/src/index.ts b/src/index.ts
index 3c16d28..2864e48 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -629,6 +629,20 @@ program
     const engine = resolveEngineMode(opts.engine || config.engine);
     const useSweetistics = shouldUseSweetistics(engine, Boolean(sweetistics.apiKey));
     const resolvedEngine = useSweetistics ? 'sweetistics' : 'graphql';
+    const credentialSource =
+      resolvedEngine === 'sweetistics'
+        ? sweetistics.apiKey
+          ? 'Sweetistics API key'
+          : 'none'
+        : opts.chromeProfile
+            ? `Chrome profile "${opts.chromeProfile}"`
+            : opts.firefoxProfile
+                ? `Firefox profile "${opts.firefoxProfile}"`
+                : config.chromeProfile
+                    ? `Chrome profile "${config.chromeProfile}"`
+                    : config.firefoxProfile
+                        ? `Firefox profile "${config.firefoxProfile}"`
+                        : 'env/auto-detected cookies';
 
     if (useSweetistics) {
       if (!sweetistics.apiKey) {
@@ -648,6 +662,7 @@ program
           console.log(`📧 ${result.user.email}`);
         }
         console.log(`⚙️ Engine: ${resolvedEngine}`);
+        console.log(`🔑 Credentials: ${credentialSource}`);
         return;
       }
 
@@ -682,6 +697,7 @@ program
       console.log(`🙋 Logged in as @${result.user.username} (${result.user.name})`);
       console.log(`🪪 User ID: ${result.user.id}`);
       console.log(`⚙️ Engine: ${resolvedEngine}`);
+      console.log(`🔑 Credentials: ${credentialSource}`);
     } else {
       console.error(`❌ Failed to determine current user: ${result.error ?? 'Unknown error'}`);
       process.exit(1);