From 1e52721ddb7834148243b208103d92799c28d2a6 Mon Sep 17 00:00:00 2001
From: Shawn <shawn@ourpad.casa>
Date: Thu, 21 May 2026 18:55:51 -0400
Subject: [PATCH] Add diff tracking documentation

---
 Home.md | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/Home.md b/Home.md
index e334846..534d1ee 100644
--- a/Home.md
+++ b/Home.md
@@ -4,10 +4,11 @@ Automation for exporting machine data from mycantaloupe.com.
 
 **Repo:** [shawn/cantaloupe-downloader](https://gitea.ourpad.casa/shawn/cantaloupe-downloader)
 **Local:** `~/projects/cantaloupe-downloader/`
+**Latest commit:** `e408867`
 
 ## Purpose
 
-CLI tool to authenticate with mycantaloupe.com and download the Machine List Excel export via direct HTTP (httpx) — no browser automation needed.
+CLI tool to authenticate with mycantaloupe.com and download the Machine List Excel export via direct HTTP (httpx) — no browser automation needed. Built-in diff tracking compares exports across runs.
 
 ## Architecture
 
@@ -15,8 +16,9 @@ CLI tool to authenticate with mycantaloupe.com and download the Machine List Exc
 - **`src/download.py`** — Export download automation
   - Authenticate → verify access → POST `/cs4/VueMachineList/ExcelExport` → save .xlsx
 - **`cantaloupe/`** — Click CLI wrapper (`python -m cantaloupe export`)
-  - `cantaloupe/cli.py` — export + configure commands
+  - `cantaloupe/cli.py` — export + diff + configure commands
   - `cantaloupe/config.py` — credential management (`~/.cantaloupe.env`)
+  - `cantaloupe/diff.py` — diff engine comparing xlsx by Asset ID, manifest tracking
 
 ## Quick Start
 
@@ -34,6 +36,12 @@ export CANTALOUPE_PASSWORD="your-password"
 # Download export
 python -m cantaloupe export --output ./exports/
 
+# Download + auto-compare with previous export
+python -m cantaloupe export --diff
+
+# Compare two exports
+python -m cantaloupe diff --from old.xlsx --to new.xlsx
+
 # Cron/scheduled mode
 python -m cantaloupe export --scheduled --output /data/exports/
 ```
@@ -43,6 +51,7 @@ python -m cantaloupe export --scheduled --output /data/exports/
 | Command | Description |
 |---|---|
 | `python -m cantaloupe export` | Download machine list Excel |
+| `python -m cantaloupe diff` | Compare two exports and show changes |
 | `python -m cantaloupe configure` | Save credentials to `~/.cantaloupe.env` |
 
 ### Export Options
@@ -52,9 +61,29 @@ python -m cantaloupe export --scheduled --output /data/exports/
 | `-o, --output PATH` | Output directory or file path |
 | `--headless / --visible` | Browser mode for Playwright fallback |
 | `--scheduled` | Non-interactive cron mode |
+| `--diff / --no-diff` | Auto-compare with previous export after download |
 | `--email TEXT` | Override account email |
 | `--password TEXT` | Override account password |
 
+### Diff Options
+
+| Flag | Description |
+|---|---|
+| `--from PATH` | Older xlsx file (default: auto from manifest) |
+| `--to PATH` | Newer xlsx file (default: auto from manifest) |
+| `--id-column NAME` | Column to use as unique key (auto-detected) |
+| `--json` | Output machine-readable JSON |
+
+## Diff Tracking
+
+Compares two Excel exports keyed on **Asset ID** (auto-detected, case-insensitive).
+Reports:
+- 🟢 New machines added
+- 🔴 Machines removed
+- 🟡 Machines with changed fields
+
+Manifest at `~/.cantaloupe-exports/manifest.json` tracks export history for auto-diff.
+
 ## Credential Priority
 
 1. `CANTALOUPE_EMAIL` / `CANTALOUPE_PASSWORD` environment variables
@@ -71,7 +100,7 @@ See [API Investigation](https://gitea.ourpad.casa/shawn/cantaloupe-downloader/wi
 
 ## Test Status
 
-86 tests passing (27 auth + 20 download + 39 CLI) as of commit `9c3d3ef`.
+130 tests passing (27 auth + 20 download + 39 CLI + 44 diff) as of commit `e408867`.
 
 ## Environment Variables