From 215f16a1508b56a4ff7c45bb11ab5a3f232df72e Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Thu, 7 May 2026 11:18:30 -0400
Subject: [PATCH] Add README and requirements.txt

---
 README.md        | 78 ++++++++++++++++++++++++++++++++++++++++++++++++
 requirements.txt |  2 ++
 2 files changed, 80 insertions(+)
 create mode 100644 README.md
 create mode 100644 requirements.txt

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..21b0848
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# Stampli Bulk Editor
+
+Mac desktop app for bulk-editing invoice pay dates in Stampli. Uses Playwright to automate the Stampli web UI through a real Chromium browser session.
+
+## What It Does
+
+Two operations, available via GUI or CLI:
+
+- **Edit Pay Dates** — Scans the "Ready to Pay" grid, calculates the correct pay date for each invoice (5 business days before the due date), and bulk-updates any rows that differ. After editing, optionally filters to error-free rows, selects all, and clicks Pay Invoices.
+- **Scan Pending** — Reads the "Pending Approval" grid and flags invoices where the pay date doesn't match the expected calculation.
+
+## Setup
+
+```bash
+# Create a virtual environment and install dependencies
+uv venv && source venv/bin/activate
+uv pip install -r requirements.txt
+
+# Install Chromium for Playwright
+playwright install chromium
+```
+
+## Usage
+
+### GUI (recommended)
+
+```bash
+python stampli_gui.py
+```
+
+Select an operation, optionally enable Dry Run, and click Run. The app launches a persistent Chromium browser — log in to Stampli on first use and the session is saved for future runs.
+
+### CLI
+
+```bash
+# Preview changes without editing
+python edit_pay_dates.py --dry-run
+
+# Edit pay dates
+python edit_pay_dates.py
+
+# Only run the filter/select/pay step
+python edit_pay_dates.py --filter-only
+
+# Interactive inspect mode (debug)
+python edit_pay_dates.py --inspect
+
+# Scan pending approvals for incorrect dates
+python scan_pending.py
+```
+
+## Building the Mac App
+
+```bash
+pyinstaller stampli_gui.spec
+```
+
+The bundled `.app` is written to `dist/Stampli Bulk Editor.app`. It expects Playwright's Chromium to be installed at `~/Library/Caches/ms-playwright/` (the standard Playwright cache location).
+
+## Configuration
+
+Config is stored at `~/Library/Application Support/Stampli Bulk Editor/config.json`. Defaults:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `stampli_url` | Ready to Pay dashboard URL | Starting page for edit mode |
+| `date_format` | `%m/%d/%Y` | Date format used in the grid |
+| `days_before_due` | `5` | Business days before due date to set pay date |
+
+## Project Structure
+
+```
+stampli_core.py      # Shared logic: browser management, grid scanning, date calculation, editing
+stampli_gui.py       # tkinter GUI
+edit_pay_dates.py    # CLI for editing pay dates
+scan_pending.py      # CLI for scanning pending approvals
+stampli_gui.spec     # PyInstaller build spec (arm64 macOS)
+```
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..769ca9e
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,2 @@
+playwright>=1.40
+pyinstaller>=6.0