improve README

Author: samfrm

README.md

@@ -1,119 +1,114 @@
-## reflex — HTTPS referrer emulation for analytics testing
+## reflex — Local HTTPS referrer emulator ⚡️
 
-**Reflex** is a lightweight CLI tool helps growth, marketing, and analytics teams reliably emulate inbound referrals (e.g., from `https://news.google.com`) in modern browsers. It does this by:
+Emulate real inbound referrers in modern browsers — safely and repeatably.
 
-- Mapping a chosen referrer hostname to your machine via the system hosts file
-- Serving a locally trusted HTTPS site for that hostname (certs via mkcert)
-- Issuing a redirect (302/meta/JS) to your target URL so the browser sends the correct `Referer`
+✨ What it does
+- 🧭 Maps a referrer host to your machine (`/etc/hosts`)
+- 🔒 Serves a locally trusted HTTPS site (certs via mkcert)
+- 🚀 Redirects to your target so the browser sends a real `Referer`
 
-This enables safe, repeatable end-to-end tests of attribution, A/B splits, and analytics pipelines without fragile header spoofing extensions.
+Perfect for attribution tests, analytics pipelines, and E2E growth flows.
 
-Important: This tool modifies your hosts file and runs a local HTTPS server. It restores cleanly on exit, and you can run `reflex cleanup` at any time.
+⚠️ Requires sudo/admin (modifies `/etc/hosts`, binds 443)
 
-How it works
+### 🧩 Visual Flow
 
-- Host spoof: Adds a tagged line like `127.0.0.1 news.google.com # reflex-managed` to your hosts file
-- HTTPS: Generates a locally trusted certificate for the hostname with `mkcert`
-- Redirect: Serves a small HTTPS site on that host which redirects to your target; the browser sends a real `Referer` header per current referrer policies
+```text
+   🧑‍💻 You click the referrer URL
+             │
+             ▼
+   /etc/hosts ➜ 127.0.0.1   (spoofs referrer host)
+             │
+             ▼
+   🔒 Reflex HTTPS server (mkcert‑trusted)
+             │  302 / <meta> / JS → https://your-app.example
+             ▼
+   🎯 Target site receives Referer: https://news.google.com/
+```
 
-Install
+### 🚀 Quick Start
 
-- Requires Go 1.21+ for building
-- Requires `mkcert` (https://github.com/FiloSottile/mkcert)
-- Requires sudo/admin privileges (the CLI runs with sudo)
+1) One‑time (Linux only) — share CA between root and your user
 
-Build from source
+```bash
+sudo mkcert -install     # system trust store
+mkcert -install          # your user’s Firefox/Chromium trust
+sudo mkdir -p /etc/mkcert
+sudo cp -a "$(mkcert -CAROOT)/." /etc/mkcert/
+sudo chmod 755 /etc/mkcert && sudo chmod 644 /etc/mkcert/*
+```
 
-- `go build ./cmd/reflex`
-- Or: `go run ./cmd/reflex --help`
+• macOS: `brew install mkcert nss && sudo mkcert -install`
+• Windows: `choco install mkcert` then `mkcert -install` (admin PowerShell)
 
-One-time Setup (Linux)
+2) Run a referrer → target flow
 
-To avoid the common "no Firefox/Chrome security databases found" issue when running under sudo, pin a shared CAROOT used by both root and your user.
+```bash
+sudo reflex run \
+  --referrer https://news.google.com \
+  --target   https://your-app.example
+```
 
-1. Install the local CA into the system trust store and your user’s browser trust store:
+Reflex opens your default browser (as your normal user) in a private window and serves a small referrer page using HTTPS with a trusted local cert.
 
-- `sudo mkcert -install` # system trust store
-- `mkcert -install` # your user’s Firefox/Chromium trust
+### 🔧 Install / Build
 
-2. Pin a shared CAROOT so root and user use the same CA:
+- 🦫 Go 1.21+
+- 🔑 `mkcert` in PATH
+- 🏗️ Build: `go build ./cmd/reflex`
+- 📖 Help:  `go run ./cmd/reflex --help`
 
-- `sudo mkdir -p /etc/mkcert`
-- `sudo cp -a "$(mkcert -CAROOT)/." /etc/mkcert/`
-- `sudo chmod 755 /etc/mkcert && sudo chmod 644 /etc/mkcert/*`
+### 🕹️ Commands
 
-After this, reflex (which runs with sudo) uses `/etc/mkcert` automatically to generate certs that match your user’s trusted CA.
+- ▶️ `reflex run`     Start HTTPS server, spoof host, open browser
+- 🧹 `reflex cleanup` Remove hosts entry and generated certs (add `--all` to wipe everything)
+- 🔍 `reflex status`  Show current state for a referrer
 
-Notes for other platforms:
+### 🎛️ Flags you’ll actually use
 
-- macOS: `brew install mkcert nss && sudo mkcert -install` (no pinned CAROOT needed)
-- Windows: `choco install mkcert` then `mkcert -install` in an elevated shell
+- 🔗 `--referrer`          Referrer URL or host (required)
+- 🎯 `--target`            Target URL to navigate to (required)
+- 🔁 `--method`            Redirect: meta (default), 302, js
+- 🛡️ `--referrer-policy`   `origin-when-cross-origin` (default) or `unsafe-url` for full URL
+- 🕶️ `--private`           Open browser in incognito/private mode (default true)
+- 🚫 `--no-browser`        Don’t auto‑open a browser
 
-Run with sudo
+More:
+- ⏱️ `--delay` (meta/js, ms), 🔌 `--port` (default 443, falls back to 8443), 🗂️ `--keep-certs`, 🧪 `--no-hosts`, 🧹 `--force-unlock`
 
-- reflex requires elevated privileges to modify `/etc/hosts` and bind to port 443.
-- Always run commands with sudo, e.g.: `sudo reflex run --referrer ... --target ...`
+### 🩹 Troubleshooting (fast answers)
 
-Quick start
+- 🥚 Empty `document.referrer`?
+  - Use `--method meta` (default) or `--method js`
+  - Try `--referrer-policy unsafe-url` for full URL referrers
+- 🧪 Linux mkcert warning under sudo (“no Firefox/Chromium DBs”)?
+  - Complete the one‑time setup above (shared CAROOT in `/etc/mkcert`)
+- 🖥️ Browser didn’t open?
+  - Reflex launches the browser as your non‑root user. If DBus/XDG is missing (headless), copy the printed URL and open manually
+- 🌐 Hosts entry not taking effect?
+  - Check VPNs/enterprise DNS overrides. `sudo reflex status --referrer <host>` helps debug
 
-- Spoof Google News and redirect to your site:
-  - `reflex run --referrer https://news.google.com --target https://your-app.example`
+### 🧼 Safety and cleanup
 
-Commands
+- 🏷️ Hosts entries are tagged (`# reflex-managed`) for safe removal
+- 🕰️ A timestamped hosts backup is written before first modification
+- 🧽 `reflex cleanup --referrer <host>` removes the entry and temp certs (unless `--keep-certs`)
 
-- `reflex run`: Start HTTPS server, spoof host, and open browser
-- `reflex cleanup`: Remove hosts entry and generated certificates for a host; add `--all` to remove all reflex-managed entries, all certs, and the lock
-- `reflex status`: Inspect whether hosts entry and certs exist
+### 🧰 Dev notes
 
-Run options
+Code map:
+- 🧩 `cmd/reflex`  CLI
+- 🗂️ `internal/hosts`  Hosts manager
+- 🔑 `internal/certs`  mkcert bridge (Linux uses `/etc/mkcert`)
+- 🔒 `internal/server` HTTPS redirector
+- 🌐 `internal/browser` Browser opener (drops sudo → user, incognito)
+- 🛠️ `internal/util`   Port/lock/helpers
 
-- `--referrer`: Referrer URL or hostname (required)
-- `--target`: Target URL to navigate to (required)
-- `--method`: Redirect strategy: meta (default), 302, js
-- `--delay`: Delay for meta/js methods in ms (default 1500)
-- `--port`: TLS port (default 443). Falls back to 8443 if unavailable
-- `--no-browser`: Do not open the browser automatically
-- `--private`: Open browser in incognito/private mode (default true)
-- `--keep-certs`: Keep generated certs after exit
-- `--no-hosts`: Do not modify hosts (advanced)
-- `--force-unlock`: Forcefully clear a stale lock before starting
-- `--referrer-policy`: Explicit Referrer-Policy for the referrer page (default `origin-when-cross-origin`). Use `unsafe-url` to send the full URL to cross-origin targets.
+🧪 Tests: `go test ./...` (unit tests generate self‑signed certs; no mkcert required)
 
-Notes
+### 🗺️ Roadmap
 
-- Elevated privileges: Binding to 443 and editing the hosts file typically require admin/sudo
-- If 443 is busy or you lack privileges, the server falls back to 8443 and opens `https://<host>:8443`
-- Modern default referrer policy is `strict-origin-when-cross-origin`, so your target receives at least the origin
-- HSTS domains: A valid, trusted certificate is required. `mkcert` provides a locally trusted CA for this purpose. Reflex now runs `mkcert -install` for you (idempotent) before generating certs; if it fails, you’ll see a clear instruction.
-
-Cleanup and safety
-
-- Tagged hosts entries let reflex remove only what it added
-- A timestamped backup of the hosts file is created adjacent to the file on first write
-- On exit or `reflex cleanup --referrer <host>`, reflex removes the tagged line and generated certs (unless `--keep-certs`)
-
-Troubleshooting
-
-- Browser blocks the page: Ensure `mkcert` is installed and its root CA is trusted
-- Empty `document.referrer`: Set `--referrer-policy origin-when-cross-origin` (default) for origin referrers, or `--referrer-policy unsafe-url` to send the full path. You can also try `--method meta` or `--method js` if your stack handles those better.
-- Linux note: If you see "no Firefox and/or Chrome/Chromium security databases found" while using sudo, complete the One-time Setup above to pin a shared CAROOT at `/etc/mkcert`.
-- Wrong host is opened: Verify the URL shown by the tool and that your browser didn’t cache an older page
-- Hosts entry doesn’t apply: Some VPN/enterprise setups override name resolution; try disabling the VPN temporarily
-
-Development
-
-- Code layout:
-  - `cmd/reflex`: CLI entrypoint and subcommands
-  - `internal/hosts`: Safe hosts file management with tagged lines
-  - `internal/certs`: mkcert integration and cert lifecycle
-  - `internal/server`: HTTPS server and redirect strategies
-  - `internal/browser`: Cross-platform browser opener
-  - `internal/util`: Utilities (hostname parsing, port probing, locking)
-- Tests: `internal/hosts` and `internal/util` include basic unit tests you can run with `go test ./...`
-
-Roadmap
-
-- Optional DNS-based spoofing mode (no hosts edits)
-- CAP_NET_BIND_SERVICE support on Linux to bind 443 without root
-- UI control panel and session recorder
-- Native installers and signed binaries
+- 🧭 Optional DNS spoofing mode (no hosts edits)
+- 🧷 CAP_NET_BIND_SERVICE on Linux to bind 443 without sudo
+- 🖱️ Simple UI control panel / recorder
+- 📦 Packages / signed binaries