init: slopbot scaffold

1 files changed, 33 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0ffb3a1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,33 @@
+# slopbot
+
+Zulip bot for [meshheads.org](https://zulip.meshheads.org) that replies with stock prices when it sees `$TICKER` patterns in messages.
+
+## Usage
+
+Post `$NVDA` or `$AAPL is mooning` in any stream and slopbot replies with the current price.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+cp .zuliprc.example .zuliprc
+# edit .zuliprc with your bot credentials
+python main.py
+```
+
+Get your `.zuliprc` from Zulip: Settings → Bots → your bot → download config.
+
+## Architecture
+
+- `main.py` — single-file bot, raw `zulip` event loop (no framework)
+- `fetch_price(ticker)` — isolated data layer, easy to swap yfinance for a real API
+- Regex: `\$([A-Z]{1,5})` — matches 1-5 uppercase letters after `$`
+- Deduplicates tickers per message, replies in-place (same stream + topic)
+
+## Extending
+
+Future ideas:
+- Swap `fetch_price` for Finnhub/Polygon for real-time data
+- Add LLM commentary on price moves
+- Support crypto tickers
+- Add `@slopbot summarize $NVDA` command style