Add README and requirements.txt

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)
+```

requirements.txt

@@ -0,0 +1,2 @@
+playwright>=1.40
+pyinstaller>=6.0