docs: add README

README.md

@@ -0,0 +1,127 @@
+# Discord Feed Bots 🤖
+
+Automated feed system that posts daily AI/agent digests to Discord channels. Zero LLM tokens — just fetch, format, and webhook.
+
+## Feeds
+
+| Feed | What it does | Schedule |
+|------|-------------|----------|
+| **Reddit Digest** | Top posts from AI subreddits (r/LocalLLaMA, r/ClaudeAI, r/ChatGPT, etc.) | Daily 7am MT |
+| **Trending Repos** | Trending GitHub repos in the AI/agent space | Daily 7am MT |
+| **New AI Repos** | New repos (<7 days old) with >100 stars | Daily 7am MT |
+| **Twitter/X** | Trending AI threads via Twitter API v2 | Daily 7am MT |
+| **Claude Code Releases** | New version detection from npm registry | Every 6h |
+| **Weekly Trends** | Clustered trend analysis using qdrant + ollama | Sundays 9am MT |
+
+## Quick Start
+
+```bash
+bun install
+
+# Run a single feed (outputs to stdout)
+bun run feed reddit
+bun run feed trending
+bun run feed new-repos
+bun run feed twitter
+bun run feed claude-releases
+bun run feed weekly-trends
+
+# Run all feeds
+bun run feed all
+
+# Post directly to Discord via webhooks
+bun run src/post.ts reddit
+bun run src/post.ts all
+```
+
+## Tools
+
+### Image Generation
+```bash
+bun run src/tools/image-gen.ts "your prompt here"
+```
+Uses Google AI (Gemini 3 Pro Image Preview). Outputs to `/mnt/work/tmp/image-gen/`.
+
+### Stem Splitting
+```bash
+bun run src/tools/stem-split.ts "artist - song name"
+```
+Downloads audio via yt-dlp, separates stems using UVR5 (audio-separator). Models stored at `/mnt/work/models/audio-separator/`.
+
+## Architecture
+
+```
+src/
+  feeds/
+    reddit-digest.ts        — Reddit JSON API (7 subreddits, score ≥ 50)
+    github-trending.ts      — GitHub search API (AI/agent topics)
+    new-ai-repos.ts         — GitHub search (created last 7 days, >100★)
+    claude-code-releases.ts — npm registry version tracking
+    twitter-ai.ts           — Twitter API v2 search/recent
+    weekly-trends.ts        — qdrant + ollama pipeline
+  tools/
+    image-gen.ts            — Google AI image generation
+    stem-split.ts           — UVR5 audio stem separation
+  config.ts                 — All feed configuration
+  utils.ts                  — Shared helpers
+  index.ts                  — CLI entry point
+  post.ts                   — Webhook posting to Discord
+```
+
+## How It Works
+
+1. **Feeds** scrape public APIs (Reddit, GitHub, Twitter, npm)
+2. **Filters** apply score/age/relevance thresholds
+3. **Formatter** outputs Discord-ready markdown
+4. **Poster** sends to Discord channels via webhooks
+5. **Timers** (systemd) trigger everything on schedule
+
+No AI is used for the daily feeds — just HTTP requests and string formatting.
+
+The **weekly trends** feed is the exception: it embeds posts with `nomic-embed-text` (ollama), clusters them in qdrant, and summarizes with `glm-4.7-flash` — all local, zero API cost.
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and fill in:
+
+```
+TWITTER_BEARER_TOKEN=...
+QDRANT_URL=...
+QDRANT_API_KEY=...
+OLLAMA_HOST=http://localhost:11434
+GOOGLE_AI_API_KEY=...
+WEBHOOK_REDDIT=...
+WEBHOOK_TRENDING=...
+WEBHOOK_NEW_REPOS=...
+WEBHOOK_CLAUDE_RELEASES=...
+WEBHOOK_TWITTER=...
+WEBHOOK_WEEKLY_TRENDS=...
+```
+
+## Deployment
+
+Runs as systemd user timers:
+
+```bash
+# Check timer status
+systemctl --user list-timers | grep feed
+
+# Manual trigger
+systemctl --user start feed-bot-daily.service
+
+# Logs
+cat /tmp/feed-bot.log
+```
+
+## Adding a New Feed
+
+1. Create `src/feeds/my-feed.ts` exporting `run(): Promise<string>`
+2. Add config to `src/config.ts`
+3. Add to `COMMANDS` in `src/index.ts`
+4. Add to `FEEDS` in `src/post.ts` with webhook env var
+5. Create Discord webhook for the target channel
+6. Add to systemd timer or create a new one
+
+## License
+
+MIT