matebot 0.2.0__tar.gz

matebot-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install ".[all,dev]"
+      - run: ruff check src tests
+      - run: pytest -q

matebot-0.2.0/.github/workflows/docker.yml

@@ -0,0 +1,35 @@
+name: Docker
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/matebot
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=semver,pattern={{version}}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

matebot-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,20 @@
+name: Release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing (OIDC), no tokens stored
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

matebot-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+result
+dist/
+state.json

matebot-0.2.0/AGENTS.md

@@ -0,0 +1,101 @@
+# Agent instructions for MATEbot
+
+You are likely here because a human asked their AI assistant to help with
+MATEbot — either to **set it up** for their GaggiMate espresso machine or to
+**work on the code**. Both playbooks follow.
+
+## What this is
+
+MATEbot watches a GaggiMate machine over its local WebSocket API, messages the
+user after every shot (Telegram or Discord) to log rating/beans/grind/doses,
+writes those notes back into the machine's own shot history, and optionally
+archives everything to a git repo with a generated shot-journal site.
+
+## Playbook: helping someone set it up
+
+Adapt to the user's skill level — ask what they have before prescribing.
+The decision tree:
+
+1. **Where will it run?** It needs any always-on device on the same network
+   as the machine: a Raspberry Pi, NAS, home server, old laptop. No port
+   forwarding, no domain — outbound internet only.
+2. **Pick an install path:**
+   - Most users → **Docker**: copy `docker-compose.example.yml`, fill in env
+     vars, `docker compose up -d`. Image: `ghcr.io/alexnly/matebot:latest`
+     (multi-arch, Raspberry Pi works).
+   - Python users → `pip install "matebot[telegram] @ git+https://github.com/AlexNly/MATEbot"`,
+     then `matebot run` (systemd unit or `screen` for persistence).
+   - NixOS users → flake input + `services.matebot` module (see README).
+3. **Telegram bot** (the fiddly part for novices — walk them through it):
+   1. In Telegram, talk to `@BotFather` → `/newbot` → pick a name → copy the
+      token (looks like `123456:ABC-...`). Never paste tokens into git.
+   2. Have the user send their new bot any message.
+   3. Get the chat id: `https://api.telegram.org/bot<TOKEN>/getUpdates` →
+      `result[0].message.chat.id`.
+   4. `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` go into the environment
+      (compose file, EnvironmentFile, or shell).
+4. **Machine address**: set `MATEBOT_MACHINE_HOST`. Prefer the machine's IP
+   over `gaggimate.local` (mDNS is flaky on some networks) and recommend a
+   static DHCP lease in the router.
+5. **Verify**: start the bot, run a ≥10 s brew-mode shot (an empty blind
+   basket works; water/steam modes do not trigger). The questionnaire should
+   arrive within seconds of the shot ending.
+6. **Optional extras**, in ascending effort: journal repo + GitHub Pages
+   (README "Publishing your journal"), dial-in hints (on by default), bean
+   bag tracking (`/newbag`), smart plug hooks for cold-start `/wake`
+   (README "Smart plug cold start").
+
+Common failure modes: token/chat id swapped or quoted wrong; bot and machine
+on different networks/VLANs; machine powered off at a dumb power strip;
+shots shorter than `MATEBOT_MIN_SHOT_S` (default 10 s) being ignored;
+firmware older than v1.7 (no binary shot logs — unsupported).
+
+## Playbook: working on the code
+
+- Layout: `src/matebot/` — `machine.py` (WS/HTTP client), `watcher.py` (shot
+  detection), `conversation.py` (questionnaire engine, messenger-agnostic),
+  `messengers/` (Telegram/Discord backends), `commands.py` (slash commands),
+  `hints.py`, `bags.py`, `digest.py` (features), `sync.py` (git archive),
+  `sitegen.py` + `web/` (journal site), `plot.py` (Telegram PNG chart),
+  `slog.py` (binary format decoder — start here to understand the data).
+- Dev loop: `pip install -e ".[all,dev]"` then `pytest -q` and
+  `ruff check src tests`. Or `nix develop`.
+- Contribution flow: branch → PR → CI must pass (branch protection, no direct
+  pushes to `main`) → squash merge. Keep commits/PRs single-purpose.
+- Tests are required for behavior changes. The conversation engine is tested
+  against a `FakeMessenger`; the watcher against a recorded frame fixture
+  (`tests/fixtures/status_frames.jsonl`); the decoder against a real shot
+  (`tests/fixtures/000004.slog` — golden values in `test_slog.py`).
+
+### GaggiMate firmware gotchas (hard-won; do not rediscover these)
+
+- `req:history:notes:save`: the request-level `id` becomes the notes filename
+  verbatim. Older firmware reads the zero-padded name (`000059.json`),
+  current nightlies the unpadded one (`59.json`) — MATEbot saves under BOTH.
+  `rating` must be a number, every other field a string.
+- `req:change-mode` gets **no response** — never wait for one (fire-and-forget
+  via `send_event`; confirmation comes from the status stream).
+- Missing files under `/api/history/` return **HTTP 200 with gzipped SPA
+  index.html**, not 404 — validate content (`SHOT` magic / leading `{`) on
+  every fetch.
+- The ESP32 drops WebSocket clients whenever its send queue fills (e.g. the
+  web UI is open). Reconnect loops must be bulletproof; nothing may
+  crash-loop on a dropped socket.
+- New-shot ids come from polling `/api/history/index.bin` (`flags & 1`,
+  `id > last_known`) — never from `req:history:list` (heavy on the ESP32)
+  and never from timestamps (`startEpoch` is wrong without NTP).
+- Shot files are finalized up to ~1 min after the pump stops (bluetooth
+  scale settle time).
+
+### License boundary (important)
+
+GaggiMate's own source (including its web UI) is **CC BY-NC-SA** — it must
+never be copied into this MIT repo. Matching its *look* (colors, layout,
+axis ranges) via independent implementation is fine and is what
+`web/app.js` and `plot.py` do.
+
+### Secrets
+
+Tokens live in the environment only. `settings.json` written to data repos
+must keep `wifiSsid`, `wifiPassword`, `apPassword`, `haPassword` redacted
+(`machine.py` does this — keep it that way).

matebot-0.2.0/CLAUDE.md

@@ -0,0 +1,2 @@
+See [AGENTS.md](AGENTS.md) — setup playbook, dev guide, firmware gotchas,
+and the license boundary all live there.

matebot-0.2.0/Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.13-slim
+
+# git + ssh are only needed for the optional data-repo sync
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git openssh-client \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip install --no-cache-dir ".[all]"
+
+RUN useradd -m -u 1000 matebot
+USER matebot
+ENV MATEBOT_STATE_DIR=/data
+VOLUME /data
+
+ENTRYPOINT ["matebot"]
+CMD ["run"]

matebot-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Nicolay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matebot-0.2.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: matebot
+Version: 0.2.0
+Summary: The proactive companion for GaggiMate espresso machines: post-shot logging bot, .slog decoder, shot-journal site generator
+Project-URL: Homepage, https://github.com/AlexNly/matebot
+Project-URL: Issues, https://github.com/AlexNly/matebot/issues
+Author: Alexander Nicolay
+License-Expression: MIT
+License-File: LICENSE
+Keywords: coffee,discord,espresso,gaggimate,homelab,telegram
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: all
+Requires-Dist: discord-py>=2.3; extra == 'all'
+Requires-Dist: matplotlib>=3.8; extra == 'all'
+Requires-Dist: matrix-nio>=0.24; extra == 'all'
+Requires-Dist: python-telegram-bot<23,>=21; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: discord
+Requires-Dist: discord-py>=2.3; extra == 'discord'
+Provides-Extra: matrix
+Requires-Dist: matrix-nio>=0.24; extra == 'matrix'
+Provides-Extra: plots
+Requires-Dist: matplotlib>=3.8; extra == 'plots'
+Provides-Extra: telegram
+Requires-Dist: python-telegram-bot<23,>=21; extra == 'telegram'
+Description-Content-Type: text/markdown
+
+# matebot
+
+A post-shot companion for [GaggiMate](https://gaggimate.eu) espresso machines.
+
+I kept forgetting to log my shots. Not for lack of caring — but after every
+shot the ritual was: pull out the phone, open the web UI, find Shot History,
+tap edit, type everything in. Most days that didn't happen, and by 23:47,
+lying in bed, the grind setting of today's best shot was gone for good.
+
+matebot turns the workflow around: when a shot finishes, the machine messages
+*you* and asks the few things you'd otherwise forget — rating, taste, beans,
+grind, doses. Thirty seconds of tapping while you sip. The answers are written
+straight back into GaggiMate's own Shot Notes, exactly as if you'd typed them
+into the web UI.
+
+<p align="center">
+  <img src="docs/screenshots/telegram-chat.png" width="420" alt="matebot asking for a shot rating on Telegram right after the shot finished">
+</p>
+
+## What it does
+
+- Watches the machine over its WebSocket API and detects finished brew shots
+  (backflush/descale/flush runs and anything under 10 s are ignored).
+- Runs a short questionnaire via **Telegram** or **Discord** (Matrix planned),
+  with one-tap "same as last shot" defaults for beans, grind and dose.
+- Saves the answers into the machine's shot history — GaggiMate stays the
+  source of truth, with or without matebot.
+- Optionally archives every shot (`.slog` + notes), your brew profiles and
+  machine settings (credentials redacted) to a git repository after each shot.
+- Generates a static **shot journal** from that archive, ready for GitHub
+  Pages. Because the journal lives outside the machine, it survives firmware
+  updates and downgrades, a dying SD card, or a water-damaged machine.
+- Ships a standalone `.slog` decoder (`matebot decode shot.slog --csv`).
+- After a sour, bitter or low-rated shot it suggests the next dial-in step
+  (grind → ratio → temperature, one variable at a time), following
+  [modsmthng's Automatic Pro cheat sheet](https://modsmthng.github.io/Automatic-Pro/)
+  — disable with `MATEBOT_HINTS=0`.
+
+## The shot journal
+
+[Live example](https://alexnly.github.io/GAGGIMATE-0614/) — every shot with
+the familiar combined pressure/flow/temperature chart, phase markers, ratings
+and notes.
+
+<p align="center">
+  <img src="docs/screenshots/journal-list.png" width="49%" alt="Shot journal list with ratings, ratios and peak pressure">
+  <img src="docs/screenshots/journal-detail.png" width="49%" alt="Per-shot detail with combined pressure/flow/temperature chart">
+</p>
+
+## Install
+
+### Docker
+
+```bash
+mkdir matebot && cd matebot
+curl -O https://raw.githubusercontent.com/AlexNly/matebot/main/docker-compose.example.yml
+cp docker-compose.example.yml docker-compose.yml
+# edit: machine host, bot token, chat id
+docker compose up -d
+```
+
+Images are multi-arch (`amd64` + `arm64`, so a Raspberry Pi works):
+`ghcr.io/alexnly/matebot:latest`. There is no cloud service behind this —
+the bot needs to run on something in your home network that is always on.
+A Pi Zero 2 W and a USB charger is the whole data center.
+
+### pip
+
+```bash
+pip install "matebot[telegram] @ git+https://github.com/AlexNly/matebot"
+matebot run
+```
+
+### NixOS (flake)
+
+```nix
+inputs.matebot.url = "github:AlexNly/matebot";
+
+services.matebot = {
+  enable = true;
+  machineHost = "192.168.1.50";
+  environmentFile = "/etc/secrets/matebot";  # TELEGRAM_BOT_TOKEN=... / TELEGRAM_CHAT_ID=...
+  dataRepo = "/var/lib/gaggimate-journal";    # optional
+};
+```
+
+## Setup
+
+1. Telegram: create a bot with [@BotFather](https://t.me/BotFather)
+   (`/newbot`), copy the token. Message your bot once, then read your chat id
+   from `https://api.telegram.org/bot<TOKEN>/getUpdates`.
+   Discord: create an application + bot, invite it to a server, enable the
+   *message content* intent, copy the channel id.
+2. Point `MATEBOT_MACHINE_HOST` at your GaggiMate. A DHCP reservation is more
+   reliable than `gaggimate.local`.
+3. Pull a shot.
+
+## Chat commands
+
+Besides the post-shot questionnaire, the bot answers commands (any messenger):
+
+```
+/wake     turn the machine on — pings you when it's at temperature
+/sleep    back to standby
+/status   mode, boiler temperature, water level
+/last     the last logged shot (with journal link if configured)
+/fix      redo the questionnaire for the last shot
+/help     list commands
+```
+
+## Smart plug cold start (optional)
+
+GaggiMate in standby still draws power, so many people cut it at a smart
+plug — which normally kills `/wake`. Give MATEbot the plug's on/off commands
+and `/wake` becomes a true cold start (plug on → wait for the machine to
+boot → brew mode → ready ping), while `/sleep` powers everything down:
+
+```bash
+# Tasmota (Nous A1T, Eightree, ...)
+MATEBOT_WAKE_HOOK='curl -sf "http://192.168.1.60/cm?cmnd=Power%20On"'
+MATEBOT_SLEEP_HOOK='curl -sf "http://192.168.1.60/cm?cmnd=Power%20Off"'
+
+# Shelly
+MATEBOT_WAKE_HOOK='curl -sf "http://192.168.1.60/relay/0?turn=on"'
+```
+
+Any shell command works (Home Assistant webhook, `tinytuya`, zigbee2mqtt…).
+
+## Configuration
+
+Environment variables, or the same keys in `~/.config/matebot/config.toml`:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `MATEBOT_MACHINE_HOST` | `gaggimate.local` | GaggiMate hostname/IP |
+| `MATEBOT_MESSENGER` | `telegram` | `telegram` or `discord` |
+| `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` | — | Telegram credentials |
+| `DISCORD_BOT_TOKEN` / `DISCORD_CHANNEL_ID` | — | Discord credentials |
+| `MATEBOT_DATA_REPO` | — | Path to a git clone; enables archive + journal |
+| `MATEBOT_SITE_TITLE` | `Shot Journal` | Title of the generated journal |
+| `MATEBOT_JOURNAL_URL` | — | Public journal URL, used for `/last` deep links |
+| `MATEBOT_HINTS` | `1` | Dial-in hints after sour/bitter/low-rated shots |
+| `MATEBOT_STATE_DIR` | `~/.local/state/matebot` | Bot state (defaults, resume) |
+| `MATEBOT_MIN_SHOT_S` | `10` | Ignore shots shorter than this |
+| `MATEBOT_IGNORE_PROFILES` | `(?i)backflush\|descale\|flush\|clean` | Profile regex to skip |
+
+## CLI
+
+```
+matebot run                 # the bot (--replay frames.jsonl --dry-run to test)
+matebot decode SHOT.slog    # .slog -> JSON (--csv for CSV)
+matebot sitegen shots/ -o docs/ --title "My Shot Journal"
+matebot sync                # one-off journal sync (shots, profiles, settings, site)
+```
+
+## Publishing your journal on GitHub Pages
+
+1. Create a repo for your data, clone it where matebot runs, set
+   `MATEBOT_DATA_REPO` to the clone.
+2. On GitHub: Settings → Pages → Deploy from branch → `main` / `/docs`.
+3. Every shot now updates `https://<you>.github.io/<repo>/`.
+
+## How it talks to the machine
+
+Local network only — nothing leaves your LAN except the messenger API and
+your own git remote. Requires GaggiMate firmware ≥ v1.7 (binary shot logs).
+
+- `ws://<machine>/ws` — `evt:status` for shot detection,
+  `req:history:notes:save` for notes, `req:profiles:list` for backup
+- `GET /api/history/index.bin`, `<id>.slog`, `<id>.json` — shot downloads
+- `GET /api/settings` — settings backup; WiFi/AP/Home-Assistant credentials
+  are redacted before anything is written to disk
+
+The `.slog` v5 binary format (512-byte header, 26-byte samples at 250 ms) is
+documented in [`src/matebot/slog.py`](src/matebot/slog.py).
+
+### WhatsApp?
+
+There is no reasonable self-hosted WhatsApp bot API. Two workable paths:
+bridge your Telegram/Matrix chat via [mautrix](https://docs.mau.fi/bridges/),
+or Meta's WhatsApp Business Cloud API (requires a business account). Native
+support: contributions welcome.
+
+## Credits
+
+- [GaggiMate](https://gaggimate.eu) by jniebuhr — the machine controller this
+  companion talks to.
+- The journal's shot chart recreates the look of GaggiMate's own web UI
+  (independent reimplementation — GaggiMate's UI code is CC BY-NC-SA and none
+  of it is copied). Rendered with [Chart.js](https://www.chartjs.org/) and
+  chartjs-plugin-annotation (MIT, vendored).
+- The dial-in hints follow the guide from
+  [Automatic Pro cheat sheet](https://modsmthng.github.io/Automatic-Pro/) by
+  **modsmthng**.
+
+## License
+
+MIT. Not affiliated with the GaggiMate project.

matebot-0.2.0/README.md

@@ -0,0 +1,198 @@
+# matebot
+
+A post-shot companion for [GaggiMate](https://gaggimate.eu) espresso machines.
+
+I kept forgetting to log my shots. Not for lack of caring — but after every
+shot the ritual was: pull out the phone, open the web UI, find Shot History,
+tap edit, type everything in. Most days that didn't happen, and by 23:47,
+lying in bed, the grind setting of today's best shot was gone for good.
+
+matebot turns the workflow around: when a shot finishes, the machine messages
+*you* and asks the few things you'd otherwise forget — rating, taste, beans,
+grind, doses. Thirty seconds of tapping while you sip. The answers are written
+straight back into GaggiMate's own Shot Notes, exactly as if you'd typed them
+into the web UI.
+
+<p align="center">
+  <img src="docs/screenshots/telegram-chat.png" width="420" alt="matebot asking for a shot rating on Telegram right after the shot finished">
+</p>
+
+## What it does
+
+- Watches the machine over its WebSocket API and detects finished brew shots
+  (backflush/descale/flush runs and anything under 10 s are ignored).
+- Runs a short questionnaire via **Telegram** or **Discord** (Matrix planned),
+  with one-tap "same as last shot" defaults for beans, grind and dose.
+- Saves the answers into the machine's shot history — GaggiMate stays the
+  source of truth, with or without matebot.
+- Optionally archives every shot (`.slog` + notes), your brew profiles and
+  machine settings (credentials redacted) to a git repository after each shot.
+- Generates a static **shot journal** from that archive, ready for GitHub
+  Pages. Because the journal lives outside the machine, it survives firmware
+  updates and downgrades, a dying SD card, or a water-damaged machine.
+- Ships a standalone `.slog` decoder (`matebot decode shot.slog --csv`).
+- After a sour, bitter or low-rated shot it suggests the next dial-in step
+  (grind → ratio → temperature, one variable at a time), following
+  [modsmthng's Automatic Pro cheat sheet](https://modsmthng.github.io/Automatic-Pro/)
+  — disable with `MATEBOT_HINTS=0`.
+
+## The shot journal
+
+[Live example](https://alexnly.github.io/GAGGIMATE-0614/) — every shot with
+the familiar combined pressure/flow/temperature chart, phase markers, ratings
+and notes.
+
+<p align="center">
+  <img src="docs/screenshots/journal-list.png" width="49%" alt="Shot journal list with ratings, ratios and peak pressure">
+  <img src="docs/screenshots/journal-detail.png" width="49%" alt="Per-shot detail with combined pressure/flow/temperature chart">
+</p>
+
+## Install
+
+### Docker
+
+```bash
+mkdir matebot && cd matebot
+curl -O https://raw.githubusercontent.com/AlexNly/matebot/main/docker-compose.example.yml
+cp docker-compose.example.yml docker-compose.yml
+# edit: machine host, bot token, chat id
+docker compose up -d
+```
+
+Images are multi-arch (`amd64` + `arm64`, so a Raspberry Pi works):
+`ghcr.io/alexnly/matebot:latest`. There is no cloud service behind this —
+the bot needs to run on something in your home network that is always on.
+A Pi Zero 2 W and a USB charger is the whole data center.
+
+### pip
+
+```bash
+pip install "matebot[telegram] @ git+https://github.com/AlexNly/matebot"
+matebot run
+```
+
+### NixOS (flake)
+
+```nix
+inputs.matebot.url = "github:AlexNly/matebot";
+
+services.matebot = {
+  enable = true;
+  machineHost = "192.168.1.50";
+  environmentFile = "/etc/secrets/matebot";  # TELEGRAM_BOT_TOKEN=... / TELEGRAM_CHAT_ID=...
+  dataRepo = "/var/lib/gaggimate-journal";    # optional
+};
+```
+
+## Setup
+
+1. Telegram: create a bot with [@BotFather](https://t.me/BotFather)
+   (`/newbot`), copy the token. Message your bot once, then read your chat id
+   from `https://api.telegram.org/bot<TOKEN>/getUpdates`.
+   Discord: create an application + bot, invite it to a server, enable the
+   *message content* intent, copy the channel id.
+2. Point `MATEBOT_MACHINE_HOST` at your GaggiMate. A DHCP reservation is more
+   reliable than `gaggimate.local`.
+3. Pull a shot.
+
+## Chat commands
+
+Besides the post-shot questionnaire, the bot answers commands (any messenger):
+
+```
+/wake     turn the machine on — pings you when it's at temperature
+/sleep    back to standby
+/status   mode, boiler temperature, water level
+/last     the last logged shot (with journal link if configured)
+/fix      redo the questionnaire for the last shot
+/help     list commands
+```
+
+## Smart plug cold start (optional)
+
+GaggiMate in standby still draws power, so many people cut it at a smart
+plug — which normally kills `/wake`. Give MATEbot the plug's on/off commands
+and `/wake` becomes a true cold start (plug on → wait for the machine to
+boot → brew mode → ready ping), while `/sleep` powers everything down:
+
+```bash
+# Tasmota (Nous A1T, Eightree, ...)
+MATEBOT_WAKE_HOOK='curl -sf "http://192.168.1.60/cm?cmnd=Power%20On"'
+MATEBOT_SLEEP_HOOK='curl -sf "http://192.168.1.60/cm?cmnd=Power%20Off"'
+
+# Shelly
+MATEBOT_WAKE_HOOK='curl -sf "http://192.168.1.60/relay/0?turn=on"'
+```
+
+Any shell command works (Home Assistant webhook, `tinytuya`, zigbee2mqtt…).
+
+## Configuration
+
+Environment variables, or the same keys in `~/.config/matebot/config.toml`:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `MATEBOT_MACHINE_HOST` | `gaggimate.local` | GaggiMate hostname/IP |
+| `MATEBOT_MESSENGER` | `telegram` | `telegram` or `discord` |
+| `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` | — | Telegram credentials |
+| `DISCORD_BOT_TOKEN` / `DISCORD_CHANNEL_ID` | — | Discord credentials |
+| `MATEBOT_DATA_REPO` | — | Path to a git clone; enables archive + journal |
+| `MATEBOT_SITE_TITLE` | `Shot Journal` | Title of the generated journal |
+| `MATEBOT_JOURNAL_URL` | — | Public journal URL, used for `/last` deep links |
+| `MATEBOT_HINTS` | `1` | Dial-in hints after sour/bitter/low-rated shots |
+| `MATEBOT_STATE_DIR` | `~/.local/state/matebot` | Bot state (defaults, resume) |
+| `MATEBOT_MIN_SHOT_S` | `10` | Ignore shots shorter than this |
+| `MATEBOT_IGNORE_PROFILES` | `(?i)backflush\|descale\|flush\|clean` | Profile regex to skip |
+
+## CLI
+
+```
+matebot run                 # the bot (--replay frames.jsonl --dry-run to test)
+matebot decode SHOT.slog    # .slog -> JSON (--csv for CSV)
+matebot sitegen shots/ -o docs/ --title "My Shot Journal"
+matebot sync                # one-off journal sync (shots, profiles, settings, site)
+```
+
+## Publishing your journal on GitHub Pages
+
+1. Create a repo for your data, clone it where matebot runs, set
+   `MATEBOT_DATA_REPO` to the clone.
+2. On GitHub: Settings → Pages → Deploy from branch → `main` / `/docs`.
+3. Every shot now updates `https://<you>.github.io/<repo>/`.
+
+## How it talks to the machine
+
+Local network only — nothing leaves your LAN except the messenger API and
+your own git remote. Requires GaggiMate firmware ≥ v1.7 (binary shot logs).
+
+- `ws://<machine>/ws` — `evt:status` for shot detection,
+  `req:history:notes:save` for notes, `req:profiles:list` for backup
+- `GET /api/history/index.bin`, `<id>.slog`, `<id>.json` — shot downloads
+- `GET /api/settings` — settings backup; WiFi/AP/Home-Assistant credentials
+  are redacted before anything is written to disk
+
+The `.slog` v5 binary format (512-byte header, 26-byte samples at 250 ms) is
+documented in [`src/matebot/slog.py`](src/matebot/slog.py).
+
+### WhatsApp?
+
+There is no reasonable self-hosted WhatsApp bot API. Two workable paths:
+bridge your Telegram/Matrix chat via [mautrix](https://docs.mau.fi/bridges/),
+or Meta's WhatsApp Business Cloud API (requires a business account). Native
+support: contributions welcome.
+
+## Credits
+
+- [GaggiMate](https://gaggimate.eu) by jniebuhr — the machine controller this
+  companion talks to.
+- The journal's shot chart recreates the look of GaggiMate's own web UI
+  (independent reimplementation — GaggiMate's UI code is CC BY-NC-SA and none
+  of it is copied). Rendered with [Chart.js](https://www.chartjs.org/) and
+  chartjs-plugin-annotation (MIT, vendored).
+- The dial-in hints follow the guide from
+  [Automatic Pro cheat sheet](https://modsmthng.github.io/Automatic-Pro/) by
+  **modsmthng**.
+
+## License
+
+MIT. Not affiliated with the GaggiMate project.