From 66615dd3b9396573e7edf6a07452ac08f4afebb4 Mon Sep 17 00:00:00 2001
From: Shawn <shawn@ourpad.casa>
Date: Mon, 25 May 2026 20:19:00 -0400
Subject: [PATCH] Add AGENTS.md for AI agent context

---
 AGENTS.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e39c5e4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,81 @@
+# Cantaloupe Downloader — Agent Guide
+
+CLI tool for exporting machine list data (Excel .xlsx) from mycantaloupe.com. Used as the upstream data source for the Canteen asset tracking pipeline.
+
+## Stack
+
+- **Python** 3.11+, **click** (CLI framework)
+- **httpx** (async HTTP client with anti-forgery token handling)
+- **playwright** (browser automation fallback for JS challenges)
+- **openpyxl** (Excel file reading)
+- **respx** / **pytest** (testing)
+
+## Project Structure
+
+```
+cantaloupe/
+  __init__.py
+  __main__.py       # Entry: python -m cantaloupe
+  cli.py             # Click CLI: export, diff, configure commands
+  config.py          # Config file management (~/.cantaloupe.env)
+  diff.py            # Compare two Excel exports
+
+src/
+  auth.py            # Login: httpx anti-forgery token or Playwright fallback
+  download.py        # Export POST → save .xlsx
+
+tests/
+  test_auth.py
+  test_cli.py
+  test_diff.py
+  test_download.py
+
+API.md               # API investigation notes
+README.md
+requirements.txt
+```
+
+## How to Run
+
+```bash
+# Export machines list
+python -m cantaloupe export
+
+# With scheduled-output path
+python -m cantaloupe export --scheduled
+
+# Compare two exports
+python -m cantaloupe diff file1.xlsx file2.xlsx
+
+# Configure credentials
+python -m cantaloupe configure
+```
+
+## Key Architecture
+
+- **Two auth strategies:**
+  1. **Primary:** httpx — anti-forgery token extraction from HTML, form-based login
+  2. **Fallback:** Playwright — full browser automation for JS challenges
+- Config stored in `~/.cantaloupe.env` (credentials)
+- Exports go to `~/cantaloupe-exports/` with manifest tracking via `manifest.json`
+- `diff` command compares two exports cell-by-cell
+
+## Production
+
+- **CLI tool only** — no server, no systemd
+- Triggered via cron: `cantaloupe-sync.sh` runs every 6 hours
+- Part of the Canteen pipeline: Cantaloupe → downloader → sync API
+
+## Environment Variables
+
+| Var | Description |
+|-----|-------------|
+| CANTALOUPE_EMAIL | Login email |
+| CANTALOUPE_PASSWORD | Login password |
+| CANTALOUPE_OTP_SECRET | Optional TOTP secret for 2FA |
+
+## Pitfalls
+
+- Cantaloupe may show JS challenges — Playwright fallback handles this but requires browser binaries (`playwright install chromium`)
+- Export format may change on Cantaloupe's side (they're a third-party SaaS) — `diff.py` detects structural changes
+- Auth tokens expire; each run re-authenticates