docs: Expand README with detailed sections on usage, configuration, implementation, feeds, and future ideas.

README.md

@@ -1,3 +1,80 @@
-# Mainline
+# MAINLINE
 
-A full-screen terminal news stream in a Matrix/THX-1138 aesthetic — scrolling live global headlines in large block type, with per-region translation and mic-reactive glitch effects. Supports a --poetry mode for public-domain literary passages.
+> *Digital consciousness stream. Matrix aesthetic · THX-1138 hue.*
+
+A full-screen terminal news ticker that renders live global headlines in large OTF-font block characters with a white-hot → deep green gradient. Headlines auto-translate into the native script of their subject region. Ambient mic input warps the glitch rate in real time. A `--poetry` mode replaces the feed with public-domain literary passages.
+
+---
+
+## Run
+
+```bash
+python3 mainline.py            # news stream
+python3 mainline.py --poetry   # literary consciousness mode
+python3 mainline.py -p         # same
+```
+
+First run bootstraps a local `.mainline_venv/` and installs deps (`feedparser`, `Pillow`, `sounddevice`, `numpy`). Subsequent runs start immediately.
+
+---
+
+## Config
+
+At the top of `mainline.py`:
+
+| Constant | Default | What it does |
+|---|---|---|
+| `HEADLINE_LIMIT` | `1000` | Total headlines per session |
+| `MIC_THRESHOLD_DB` | `50` | dB floor above which glitches spike |
+| `_FONT_PATH` | hardcoded path | Path to your OTF/TTF display font |
+| `_FONT_SZ` | `60` | Font render size (affects block density) |
+| `_RENDER_H` | `8` | Terminal rows per headline line |
+
+**Font:** `_FONT_PATH` is hardcoded to a local path. Update it to point to whatever display font you want — anything with strong contrast and wide letterforms works well.
+
+---
+
+## How it works
+
+- Feeds are fetched and filtered on startup (sports and vapid content stripped)
+- Headlines are rasterized via Pillow into half-block characters (`▀▄█ `) at the configured font size
+- A left-to-right ANSI gradient colors each character: white-hot leading edge trails off to near-black
+- Subject-region detection runs a regex pass on each headline; matches trigger a Google Translate call and font swap to the appropriate script (CJK, Arabic, Devanagari, etc.) using macOS system fonts
+- The mic stream runs in a background thread, feeding RMS dB into the glitch probability calculation each frame
+- The viewport scrolls through a virtual canvas of pre-rendered blocks; fade zones at top and bottom dissolve characters probabilistically
+
+---
+
+## Feeds
+
+~25 sources across four categories: **Science & Technology**, **Economics & Business**, **World & Politics**, **Culture & Ideas**. Add or swap in `FEEDS`.
+
+**Poetry mode** pulls from Project Gutenberg: Whitman, Dickinson, Thoreau, Emerson.
+
+---
+
+## Ideas / Future
+
+### Performance
+- **Concurrent feed fetching** — startup currently blocks sequentially on ~25 HTTP requests; `concurrent.futures.ThreadPoolExecutor` would cut load time to the slowest single feed
+- **Background refresh** — re-fetch feeds in a daemon thread so a long session stays current without restart
+- **Translation pre-fetch** — run translate calls concurrently during the boot sequence rather than on first render
+
+### Graphics
+- **Matrix rain underlay** — katakana column rain rendered at low opacity beneath the scrolling blocks as a background layer
+- **Animated gradient** — shift the white-hot leading edge left/right each frame for a pulse/comet effect
+- **CRT simulation** — subtle dim scanlines every N rows, occasional brightness ripple across the full screen
+- **Sixel / iTerm2 inline images** — bypass half-blocks entirely and stream actual bitmap frames for true resolution; would require a capable terminal
+- **Parallax secondary column** — a second, dimmer, faster-scrolling stream of ambient text at reduced opacity on one side
+
+### Cyberpunk Vibes
+- **Keyword watch list** — highlight or strobe any headline matching tracked terms (names, topics, tickers)
+- **Breaking interrupt** — full-screen flash + synthesized blip when a high-priority keyword hits
+- **Live data overlay** — secondary ticker strip at screen edge: BTC price, ISS position, geomagnetic index
+- **Theme switcher** — `--amber` (phosphor), `--ice` (electric cyan), `--red` (alert state) palette modes via CLI flag
+- **Persona modes** — `--surveillance`, `--oracle`, `--underground` as feed presets with matching color themes and boot copy
+- **Synthesized audio** — short static bursts tied to glitch events, independent of mic input
+
+---
+
+*macOS only (system font paths hardcoded). Python 3.9+.*