RECEIPT CAPTURE V1.03 - macOS
=============================

A NOTE FROM THE AUTHOR
----------------------
I truly hope you and your family are safe. I understand that dealing with a
wildfire evacuation or insurance loss can be a terrible and stressful time.
My hope is that Receipt Capture saves you some administrative time so you can
spend more of it with your family.

Please also be patient with your claims adjuster. They are doing the best they
can to work through your claim with you, and they understand some of the stress
you are going through.

WHAT IT DOES
------------
Receipt Capture turns a smart phone into a wireless receipt camera. It runs
locally on the Mac, stores receipts under Documents/ReceiptCapture, performs
optional OCR, tracks submission batches, and exports XLSX/ZIP insurance
packages.

FIRST INSTALL OR UPDATE
-----------------------
1. Extract this ZIP in Finder.
2. Double-click INSTALL-RECEIPT-CAPTURE.command.
3. If macOS blocks the first launch because the file was downloaded, Control-
   click the .command file, choose Open, then confirm Open.
4. Receipt Capture always installs/updates the same directory:
       ~/Applications/ReceiptCapture
5. Receipt data remains separately under:
       ~/Documents/ReceiptCapture

Python 3 is required. If Python is missing and Homebrew is installed, the
installer can install Python. Otherwise it opens the official Python macOS
download page. Tesseract OCR is installed automatically when Homebrew is
available; manual entry works without OCR.

CLEAN-SLATE OPTION
------------------
Every install/update asks whether to start with a clean slate. The prompt waits
5 seconds and defaults to NO, so normal upgrades preserve all receipts/settings
without requiring input. Choose YES only when intentionally troubleshooting or
starting over. Before resetting, the installer moves the previous data into one
rolling safety folder named ReceiptCapture-PRE-RESET beside the normal data
folder.

NORMAL DAILY USE
----------------
Use either:
  * the Receipt Capture.command launcher created on the Desktop, or
  * ~/Applications/ReceiptCapture/RUN-RECEIPT-CAPTURE.command

SMART PHONE PAIRING
-------------------
Start Receipt Capture, put the Mac and phone on the same private Wi-Fi, and
scan the QR code in the dashboard. The QR contains a temporary session token.
The dashboard/exports stay Mac-only; the paired phone receives only the
capture/upload/status endpoints needed for that session.

INSURANCE CLAIM INFORMATION
---------------------------
Save Claimant / Household Name, Insurance Company, Policy Number, Insurance
Claim Reference, and Currency at the top of the dashboard. After saving, the entry form
collapses into a compact summary; use Edit Claim Information whenever a change
is needed. These values are included in Master XLSX files and insurance
submission packages. Currency applies to the whole claim; Receipt Capture does
not convert exchange rates or mix currencies within one claim. Each submission
batch retains a historical snapshot of
the claim information used when it was made.

SUBMISSIONS
-----------
Use Create New Submission Package when you are ready to send receipts to the
insurance company. Only currently Unsubmitted receipts are included. After all
required package files are created successfully, those records are marked
Submitted. Later receipts remain Unsubmitted for the next package.

Before creating the package you can choose the image size used ONLY for outgoing
submission copies:
  * Standard - current insurance-ready image quality.
  * Email-friendly - smaller copies intended to retain good receipt readability.
  * Compact - stronger reduction for difficult email attachment limits.

Your stored Originals and local receipt images are never reduced by these
submission settings. Receipt Capture estimates the package size before creation.
If the estimate is over 10 MB, the recommended option is to split the submission
into multiple normal ZIP files. Each ZIP is independently extractable and is
labelled Part X of N; the adjuster does not need special software to recombine
anything. You can instead choose to keep one larger ZIP if your email or claim
portal accepts it.

If a previously submitted receipt is edited, the historical submission remains
unchanged and the corrected receipt is reopened for correction/resubmission.

SENDING A SUBMISSION TO YOUR CLAIMS ADJUSTER
--------------------------------------------
1. Create the submission package and note the Submission Date and Claim Reference.
2. If your insurer provides a secure claim portal, prefer that method. Otherwise
   attach the generated ZIP to email only after verifying the adjuster's address.
   The ZIP contains the XLSX workbook and its matching receipt images.
3. If Receipt Capture created Part 1 of N, Part 2 of N, etc., send EVERY part.
   If they fit within your provider's limit, they can be attached to one message.
   Otherwise send separate messages clearly labelled Part X of N using the same
   Claim Reference and Submission Date.
4. If your adjuster asks for the spreadsheet as a separate attachment, open the
   ZIP and copy out the XLSX file, then attach that XLSX alongside the ZIP.
5. Before sending, verify the recipient address/claim portal, Claim Reference,
   receipt count, amounts and attachment list.
6. Keep the sent email/portal confirmation and the generated package file(s) for
   your own records.

Email and insurer portal limits vary. The 10 MB threshold in Receipt Capture is
a conservative convenience threshold, not a statement about your provider's
actual maximum attachment size.

DELETE RECEIPT
--------------
Use Delete Receipt for an accidental or unwanted scan. Receipt Capture asks for
confirmation, then removes the live database record plus both the original and
processed image files. A previously submitted receipt receives a stronger
warning: deleting the live record does not retract or alter a package that may
already have been sent, and the historical submission snapshot remains intact.
A deleted live receipt can only be recovered from a backup.

BACKUP AND RESTORE
------------------
Create Backup ZIP includes a consistent SQLite snapshot, originals, processed
receipt images, exports, and pending files. Restore Backup ZIP validates the
selected backup and automatically creates a PRE-RESTORE-SAFETY backup before
replacing live data. A receipt awaiting review must be accepted/rejected first.

Keep occasional backup ZIPs somewhere separate from the Mac used for the claim.

OCR
---
Tesseract OCR suggests merchant/date/amount. Always verify OCR before saving.

SHUTDOWN
--------
Use Exit Receipt Capture in the browser dashboard. The green SAFE TO EXIT
indicator confirms accepted receipts are saved. Pending receipt images can be
preserved for the next startup.

PRIVACY / DISCLAIMER
--------------------
See NOTICE.txt. No cloud service is required. Use Smart Phone capture only on
a private Wi-Fi network you trust. Do not use public, hotel, airport, campground
or other shared/guest Wi-Fi. Receipt Capture uses local HTTP for phone transfer;
the pairing token controls access but the application does not add TLS encryption.

If macOS/iCloud is configured to sync Documents, your own iCloud settings may
still apply. Consider FileVault for claim data stored at rest.

Receipt Capture is provided AS-IS, WITHOUT WARRANTY. It is an organizational
tool, not legal, insurance, tax or financial advice. Always verify all exported
information and your insurer's submission requirements.
