From 7df04c481fc8194bf731b2ca466e745d0bb4c0e5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 3 Dec 2025 15:39:15 +0000
Subject: [PATCH] docs: update examples and config guidance

---
 CHANGELOG.md | 30 +++++++++++++++---------------
 README.md    | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8a3702e..2afb00a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,19 +1,19 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## Unreleased
 
-## 0.1.1 — 2025-12-02
-- Updated `CreateTweet` GraphQL query ID to `TAJw1rBsjAtdNgTdlo2oeg` (was `znCVAd692dKBq9MgkEhKPQ`)
-- Added new required feature flags for December 2025 X API:
-  - `premium_content_api_read_enabled`
-  - `responsive_web_grok_*` flags (analyze, share, translate, imagine)
-  - `profile_label_improvements_pcf_label_in_post_enabled`
-  - `responsive_web_jetfuel_frame`
-- Source: [fa0311/TwitterInternalAPIDocument](https://github.com/fa0311/TwitterInternalAPIDocument)
+### Added
+- `whoami` command works with both GraphQL cookies and Sweetistics API keys.
+- Firefox cookie extraction (`--firefox-profile`) alongside existing Chrome/env/CLI credential paths.
+- Sweetistics client `getCurrentUser` with POST→GET fallback for deployments that disallow POST.
+- Colorized help banner and example block; `pnpm bird` builds then runs the CLI; no subcommand shows help.
+- JSON5 config files (`~/.config/bird/config.json5`, `./.birdrc.json5`) for defaults like engine and browser profile.
 
-## 0.1.0 — 2025-11-28
-- Initial release of `bird`, a CLI for posting tweets and replies via the Twitter/X GraphQL API.
-- Supports posting tweets, replying to existing tweets by ID or URL, and reading tweet details.
-- Credential resolution priority: CLI flags, environment variables (`AUTH_TOKEN`, `CT0`, fallbacks `TWITTER_AUTH_TOKEN`, `TWITTER_CT0`), then macOS Chrome cookies.
-- Includes credential check command and human-friendly output for tweet metadata.
-- Bundled TypeScript sources, Vitest coverage, and Biome lint/format configuration.
+### Changed
+- Default option resolution now honors config files (project then global) before env/CLI overrides.
+
+### Changed
+- `whoami` now prefers Sweetistics when an API key is present; otherwise uses Twitter cookies.
+
+### Fixed
+- Fallback to scraping the authenticated settings page when Twitter account APIs return 404, so `whoami` still resolves the user.
diff --git a/README.md b/README.md
index 58e3721..12ba58d 100644
--- a/README.md
+++ b/README.md
@@ -20,11 +20,59 @@ pnpm run binary  # Creates the 'bird' executable
 - `bird thread <tweet-id-or-url> [--json]` — show the full conversation thread.
 - `bird search "<query>" [-n count] [--json]` — search for tweets matching a query.
 - `bird mentions [-n count] [--json]` — find tweets mentioning @clawdbot.
+- `bird whoami` — print which Twitter account your cookies belong to.
 - `bird check` — show which credentials are available and where they were sourced from.
 
+### Examples
+
+```bash
+# Show the logged-in account via GraphQL cookies
+bird whoami
+
+# Use Firefox profile cookies instead of Chrome
+bird --firefox-profile default-release whoami
+
+# Send a tweet
+bird tweet "hello from bird"
+
+# Check replies to a tweet
+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.
 
+You can set persistent defaults via config files (JSON5):
+
+- Global: `~/.config/bird/config.json5`
+- Project: `./.birdrc.json5` (overrides global)
+
+Example `~/.config/bird/config.json5`:
+
+```json5
+{
+  // Default to Sweetistics unless overridden by --engine or BIRD_ENGINE
+  engine: "sweetistics",
+  // Prefer Firefox cookies by default
+  firefoxProfile: "default-release",
+  // Optional: Sweetistics defaults
+  sweetisticsApiKey: "sweet-...",
+  sweetisticsBaseUrl: "https://sweetistics.com"
+}
+```
+
+Precedence: CLI flags > environment variables > project config > global config.
+
+To default to Firefox and Sweetistics, create `~/.config/bird/config.json5`:
+
+```json5
+{
+  engine: "sweetistics",
+  firefoxProfile: "default-release",
+  sweetisticsApiKey: "sweet-..."
+}
+```
+
 ### Post a tweet
 
 ```bash