# AGENTS.md Guidance for AI agents (and humans) changing this repository. ## What this is A single-purpose service: it polls an iCalendar feed (The Events Calendar / MCR Commons) and posts events, with poster images, to one Signal group. Signal has no bot API, so sending goes through `signal-cli-rest-api` in Docker. Read `README.md` for the user-facing behaviour and setup. ## Layout ``` src/sigcal_bot/ config.py TOML loading, defaults, duration/time parsers feed.py conditional GET; validators committed only after parse expand.py iCalendar -> Event; series-ID heuristics; recurrence expansion format.py the group's post template (title/hashtags/time/venue/link) images.py page scraping (venue, og:image) + poster download/resize/cache store.py SQLite schema and all persistence scheduler.py windows, reminder planning, dispatch/batching, Bot.tick signal_client.py /v2/send HTTP client watchdog.py throttled operator alerts __main__.py CLI: run loop, --dump, --check, --once tests/ pytest; fixtures are *.ics.txt (never *.ics) ``` ## Commands ```bash python -m venv .venv && . .venv/bin/activate pip install -e '.[dev]' pytest # must pass, no network sigcal-bot --config config.toml --dump # render the feed without sending sigcal-bot --config config.toml --check # config + Signal account check sigcal-bot --config config.toml --once # one tick ``` `--dump` uses a throwaway database and never sends; keep it that way. ## Hard rules 1. **Never commit calendar data.** `*.ics` is gitignored; test fixtures must be named `*.ics.txt`. `config.toml`, `signal-data/`, `data/`, `cache/` are local-only. 2. **UTC inside, local only at the edges.** Store and compare UTC. Convert to `[calendar].timezone` only for window maths and rendering. Never use naive `datetime.now()` in code that persists a timestamp. 3. **`tick()` must never raise.** Feed, scrape, image, and send problems are logged and reported to the watchdog; the loop has to survive all of them. The one catch-all in `__main__` is a backstop, not a design. 4. **Images are optional; text is not.** Any image or scraping failure must degrade to a text-only post. Never let enrichment raise through `_compose`. 5. **Plan once, persist it.** Reminder times and outbox rows are written when an event is first seen. Do not recompute schedules on every tick; that reorders posts when the feed changes or the process restarts. 6. **Delivery is at-least-once.** Write `deliveries` and delete the outbox row only after a successful send. A crash may duplicate one post; that is accepted. Do not add silent "mark sent before send" shortcuts. 7. **No network in tests.** Inject `now`, and use the fake sender/scraper/image service patterns in `tests/test_scheduler.py` (`httpx.MockTransport` for the feed). ## Domain gotchas - **Series vs occurrence.** TEC's UID is `{postID}-{startUnix}-{endUnix}@{host}`, and the feed pre-expands recurrences. Announcements are deduped per `series_id`; reminders per `Event.key`. Changing this will spam the group with one post per occurrence. - **Feed is capped** (30 events by default) and contains no past events. Use the coverage horizon (`max(start)` of the snapshot) before marking events `gone`; otherwise a busy week "cancels" next month's events. - **No `LOCATION` on many events.** Venue/postcode come from the event page's JSON-LD (`Event.location.name` / `address.postalCode`), then the description. This is cached per URL in `pages`. - **Poster URLs are full-size originals**, sometimes WebP or a 20 MB phone photo. Always cap the download, downscale, flatten transparency onto white, and re-encode as JPEG. - **Posting windows** (`08:00–10:00`, `18:00–21:00`) are a preference, not a rule: `clamp_send_at` breaks them when the next window would miss the event minus `urgent_guard_minutes`. - **Reminder fallback.** If `start − lead` has already passed when the event is discovered, the reminder moves to the morning of the event (or earlier, if the event starts before that morning time). - **Batching.** All outbox rows due in a tick become one message (text blocks joined by blank lines, at most `max_images_per_post` attachments). ## Changing behaviour - **New post kind** (e.g. digest): add a `kind` to `outbox`, plan rows in `_sync`/a new planner, make `_dispatch` treat it like the others, add a template in `format.py`, and test planning + dispatch with a fake clock. - **New config option**: add a dataclass field in `config.py` with a sensible default, parse it in `load_config`, document it in `config.example.toml` and the README table. - **Schema change**: append to `SCHEMA` in `store.py`. There is no migration framework; deleting `data/sigcal-bot.sqlite3` re-seeds silently. ## Changelog `CHANGELOG.md` is Keep-a-Changelog format. For anything a user of the bot would notice — behaviour, configuration, CLI, operational requirements — add a bullet under `## [Unreleased]` in the right group (`Added`, `Changed`, `Fixed`, `Removed`). Internal refactors and test-only changes do not need entries. Never create version headings. No stable release exists yet; versions are cut only when a release is actually deployed, by renaming Unreleased to `## [x.y.z] - YYYY-MM-DD`. ## Before you finish - `pytest` green, `python -m pyflakes src tests` clean. - New behaviour covered by a test (especially failure paths). - User-visible changes have a `CHANGELOG.md` entry under `## [Unreleased]`. - `config.example.toml`, README and AGENTS.md still accurate. - `git status` shows no `.ics`, `config.toml`, `data/`, `cache/` or `signal-data/` files.