1 files changed, 88 insertions, 0 deletions
diff --git a/docs/shireen.md b/docs/shireen.md
new file mode 100644
index 0000000..71cbaf7
--- /dev/null
+++ b/docs/shireen.md
@@ -0,0 +1,88 @@
+# shireen
+
+News and weather bot. Fetches current weather and forecasts from wttr.in,
+and streams headlines from configurable RSS feeds. Posts fresh headlines
+automatically at a per-channel interval and deduplicates across restarts.
+
+## Dependencies
+
+No external libraries required (uses `urllib` and `xml.etree.ElementTree`).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `!weather <city>` | Current weather conditions |
+| `!forecast <city>` | Brief forecast (today + next 2 days) |
+| `!headlines [global\|mena\|egypt] [n]` | Fresh headlines, optionally filtered by label or count |
+| `!news` | Show auto-broadcast state for this channel |
+| `!news on` | Enable auto-broadcast (owner/op) |
+| `!news off` | Disable auto-broadcast (owner/op) |
+| `!news interval <min>` | Set broadcast interval in minutes (owner/op) |
+| `!news count <n>` | Set headlines per broadcast cycle (owner/op) |
+
+### Admin (owner)
+| Command | Description |
+|---------|-------------|
+| `!join #channel` | Join a channel |
+| `!part [#channel]` | Leave a channel |
+| `!chans` | List channels |
+| `!help` | Show usage (PM) |
+
+## Auto-broadcast
+
+Every 90 minutes (default, per channel) shireen posts 1 headline (default) it
+hasn't posted before. GUIDs are persisted to the data JSON so the same article
+is never repeated across restarts. The cap is 1000 seen GUIDs (oldest pruned).
+Interval and count are configurable per channel with `!news interval` and `!news count`.
+
+## URL cleaning
+
+All query strings and fragments are stripped from feed links before posting.
+News article URLs are fully identified by their path; query parameters from
+feeds are always tracking noise.
+
+## Default RSS feeds
+
+| ID | Name | Label |
+|----|------|-------|
+| `bbc_world` | BBC World | global |
+| `reuters_world` | Reuters World | global |
+| `ap_world` | AP News | global |
+| `guardian_world` | The Guardian | global |
+| `arab_news` | Arab News | mena |
+| `aljazeera` | Al Jazeera | mena |
+| `al_monitor` | Al-Monitor | mena |
+| `egypt_indep` | Egypt Independent | egypt |
+| `daily_news_egypt` | Daily News Egypt | egypt |
+
+Feeds can be modified directly in the data JSON (`feeds` array) while the bot
+is stopped. Each feed has: `id`, `name`, `url`, `label`, `enabled`.
+
+## Data file format
+
+Created automatically at `data_path` on first run:
+
+```json
+{
+  "channels": {
+    "#example": {
+      "news_enabled": true,
+      "broadcast_interval": 90,
+      "broadcast_count": 1,
+      "last_broadcast": 0
+    }
+  },
+  "feeds": [...],
+  "seen": ["guid1", "guid2"]
+}
+```
+
+## Config keys
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `[shireen] data_path` | `/var/shireen/data.json` | Path to state/config JSON (auto-created) |
+| `[shireen] broadcast_interval` | `90` | Default minutes between auto-broadcast cycles |
+| `[shireen] broadcast_count` | `1` | Default headlines posted per broadcast cycle |
+| `[shireen] headlines_count` | `1` | Default headlines returned by `!headlines` |