elfa-grvt-bot (spec)

This skill is a specification, not a packaged project. The bundled references/ files contain everything a capable agent needs to implement the bot from scratch: wire formats, algorithms in pseudocode, SQLite DDL, failure modes, test vectors, CLI surface, and the captured production bytes that serve as ground truth for the SSE parser.

Implement the runtime in Python by default. Other languages are fine as long as the contracts in references/ are respected exactly: wire formats, dedupe keys, state transitions, alert categories.

Scope: this skill sets up the bot LOCALLY

The walkthrough in this skill installs and runs the bot on the user's local machine (laptop, workstation, dev box). That is the only deployment shape this skill orchestrates end to end.

The bot's outbound-only architecture (see 01-architecture.md) makes that viable: no inbound port, no public URL, no tunnel, no reverse proxy. The receiver only opens outbound HTTPS to api.elfa.ai (SSE), *.grvt.io (orders), and optionally api.telegram.org. Once the user has filled in .env and run elfa-grvt-bot bootstrap, the bot runs.

If the user later wants to move it off their laptop (Fly.io, Railway, AWS, a VPS with systemd, etc.) that is out of scope for this skill. The bot is environment-agnostic by design, so the user (or a different skill) can figure it out: same env vars, same code, just point at a persistent volume for registry.db and run elfa-grvt-bot run under a process supervisor. The trade-offs (laptop sleep loses fires until reconnect vs. managed hosting has geo + cost considerations) are noted in 10-troubleshooting.md but not orchestrated here.

If a user asks specifically about hosting, point them at 01-architecture.md -> "Deployment shape" and let them take it from there. Do not extend this skill to drive a cloud deploy.

Do not build a webhook receiver

The previous architecture for this bot used inbound webhooks: Elfa POSTed triggers to a public HTTPS endpoint hosted by the user (cloudflared tunnel for dev, PaaS with stable hostname for prod). This is NOT how the current bot works. The current bot is SSE-only.