commit a77bb19d9b7f7eefd295d5f652285abd0843a5d2
parent 6939121b7a20d994abe76e7d72c25ef34a6ce83c
Author: Chris Roberts <chris.roberts@learningunix.net>
Date: Fri, 3 Jul 2026 11:07:02 -0500
Add README with setup, command reference, and deployment instructions
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Diffstat:
| A | README.md | | | 94 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 94 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -0,0 +1,94 @@
+# Anton
+
+A self-hosted Telegram bot for tracking recipes, managing a weekly staples
+list, and generating grocery lists. Runs as a long-polling service — no
+public webhook or reverse proxy needed. See `CLAUDE.md` for coding
+conventions/hard constraints and `SPEC.md` for the original project plan.
+
+## Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+cp .env.example .env # then fill in TELEGRAM_BOT_TOKEN (get one from @BotFather)
+.venv/bin/python3 bot.py
+```
+
+The SQLite database is created automatically on first run at the path set
+by `ANTON_DB_PATH` in `.env` (defaults to `anton.db` in the working
+directory).
+
+## Testing
+
+```bash
+.venv/bin/pytest
+```
+
+Covers quantity parsing, grocery-list merge logic, category grouping, and
+the recipe-text parser. There's no automated coverage of the Telegram
+wiring itself — that needs manual testing against a real bot token.
+
+## Commands
+
+- `/addrecipe` — add a recipe; the bot asks for a name, then you paste the
+ ingredients (freeform text copied straight from a recipe site works, or
+ the structured `<quantity> | <unit> | <name> | <category>` format for
+ precise merging later). Long pastes can span multiple messages — send
+ `/done` when finished, `/cancel` to abort.
+- `/recipes [tag/group/keyword]` — list recipes. `keto` filters by the
+ auto-suggested keto tag; a manually-created group matches next (e.g.
+ `/recipes slowcooker`); anything else searches recipe names. An exact
+ name shows that recipe's ingredients instead of a list.
+- `/recipe <name>` — show one recipe's ingredients.
+- `/instructions <name>` — show one recipe's instructions.
+- `/instructions add <name>` — paste instructions for a recipe (replaces
+ any existing ones); spans multiple messages the same way `/addrecipe`
+ does, send `/done` when finished.
+- `/instructions delete <name>` — clear a recipe's instructions.
+- `/tag <group>` — list recipes tagged with a group (e.g. `/tag beef`).
+- `/tag add <group>` — create a new, empty group.
+- `/tag add <recipe name>, <group>` — tag a recipe with a group (creates
+ the group if it doesn't exist yet).
+- `/tag remove <group>` — delete a group entirely, untagging it from
+ every recipe.
+- `/tag remove <recipe name>, <group>` — untag one recipe, group stays.
+- `/tags` — list all groups and how many recipes are in each.
+- `/staples` — show the staples list.
+- `/staples add <item>` / `/staples remove <item>`.
+- `/grocerylist [recipe1, recipe2, ...]` — merge staples plus named
+ recipes into one list, quantities summed where they can be, grouped by
+ ingredient category (anything uncategorized lands in one plain
+ leftover section rather than being guessed at).
+- `/add <item>` — freeform one-off add to the current grocery list.
+- `/clearlist` — reset the working grocery list.
+- `/random [tag]` — random recipe suggestion, optionally filtered.
+- `/help` — show the command list from inside Telegram.
+
+## Known limitations
+
+- Ingredient merging (summing quantities across recipes/staples) only
+ works for ingredients entered in the structured `qty | unit | name |
+ category` format. Freeform-pasted ingredients (the common case) have no
+ parsed quantity/unit, so they're never summed — they just show up as
+ separate line items.
+- Keto tagging is a rough keyword heuristic (flags things like flour,
+ sugar, rice, potato), not a real nutrition calculation. Always manually
+ overridable.
+- No recipe-URL fetching — `/addrecipe` is paste-only.
+
+## Deployment
+
+`anton-bot.service` (systemd unit) and `install.sh` are provided for
+deploying to a Proxmox LXC/VM, per `SPEC.md`. `install.sh` stages a full
+copy of the repo, installs dependencies, and runs the test suite against
+that staged copy — it only touches the live install and running service if
+those tests pass, so a broken update never overwrites a working one. Read
+the comments at the top of `anton-bot.service` for the manual steps
+(create a system user, set up `.env`, etc.) before running it:
+
+```bash
+sudo ./install.sh
+```
+
+Config (bot token, DB path) is always via `.env` / environment variables —
+never hardcoded, never committed (`.gitignore` excludes `.env` and `*.db`).
