<!-- Line count target: keep SKILL.md body under 400 lines (hard limit: 500). --> <!-- Run: wc -l SKILL.md to check. Move overflow sections to references/ with links below. -->

Expense Tracker

Captures, categorizes, and stores expense records in ~/expenses/ as monthly JSON files. Three capture modes: manual text entry (Phase 25+), photo OCR (Phase 26+), email paste (Phase 27+). All records use a unified 17-field JSON schema (see references/schema.md). All monetary values stored as integer agorot — never floats. Directory auto-created on first use.

First Use

On any expense action, check if ~/expenses/ exists. If not:

1. Create ~/expenses/ directory
2. Confirm with user: "Created ~/expenses/. Expense data will be stored in ~/expenses/YYYY/MM/receipts.json."

Before each write, auto-create the current month's directory:

~/expenses/YYYY/MM/   (e.g., ~/expenses/2026/03/)

Never prompt the user to create directories — create them silently.

Storage: Atomic Write

ALWAYS use the atomic write pattern. Never write directly to receipts.json.

Steps for every save:

1. Determine target path: ~/expenses/YYYY/MM/receipts.json (YYYY/MM from expense date)
2. Create ~/expenses/YYYY/MM/ if it does not exist
3. Read receipts.json into memory as JSON array (use [] if file does not exist)
4. Append the new record object to the array
5. Write the full updated array to ~/expenses/YYYY/MM/receipts.json.tmp
6. Rename receipts.json.tmp → receipts.json

Step 6 is atomic on any standard filesystem. A crash before step 6 leaves the existing receipts.json intact.

Record ID Format

Generate a deterministic ID for each expense:

• Format: EXP-YYYY-MMDD-NNN where NNN is a 3-digit sequence starting at 001 per day
• Example: EXP-2026-0320-001
• Sequence: count existing records with the same date prefix in receipts.json, then increment

Schema Summary

Full field spec in references/schema.md. Quick reference:

Field	Type	Example
id	string	"EXP-2026-0320-001"
date	string (YYYY-MM-DD)	"2026-03-20"
vendor	string	"Cafe Aroma"
amount_agorot	integer	4590 (= 45.90 NIS)
currency	string	"NIS"
nis_amount	integer	4590
exchange_rate	number or null	null (NIS) or 3.75 (USD)
category	string	"food"
type	string	"business" or "personal"
client	string or null	"Acme Ltd"
project	string or null	"website-redesign"
vat_amount	integer	706 (= 7.06 NIS VAT)
vat_eligible	boolean	true
description	string	"Client lunch"
source	string	"manual", "ocr", or "email"
receipt_path	string or null	"2026/03/receipts/EXP-2026-0320-001.jpg"

Categorization

Quick classification (top-level only — full taxonomy in references/categories.md):

• food — meals, groceries, restaurants, cafes
• transport — taxi, fuel, public transit, parking
• accommodation — hotels, Airbnb, short-term rentals
• office — supplies, printing, furniture, equipment
• software — SaaS subscriptions, licenses, cloud services
• communications — phone bills, internet, domain names
• professional-services — accountants, lawyers, consultants
• travel — flights, intercity trains, travel insurance
• entertainment — client entertainment, events
• other — anything that does not fit above

For type: default to "business" unless the expense is clearly personal. Ask user to confirm when ambiguous.

VAT & Currency

Run these steps during every capture's confirmation phase — after amount is confirmed, before atomic write.

VAT calculation — run during every capture:

1. Determine gross_agorot (the nis_amount in agorot)
2. vat_agorot = gross_agorot - floor(gross_agorot / 1.18)
3. Set vat_amount = vat_agorot
4. Set vat_eligible = true if type is "business", false if "personal"
   Also false if vendor is a foreign entity (billed in foreign currency — no Israeli VAT)
   See references/vat-rules.md for full eligibility rules

350 NIS threshold — check during confirmation:

If nis_amount > 35000 agorot AND vat_eligible is true:
  Display in confirmation block:
    "[WARNING] Amount exceeds 350 NIS — formal tax invoice (חשבונית מס) required to reclaim VAT.
     Do you have a tax invoice? (yes / no)"
  User "yes" → keep vat_eligible: true
  User "no" / "receipt only" → set vat_eligible: false; append "[receipt only — no חשבונית מס]" to description

Multi-currency — run when currency is NOT NIS:

1. User provides amount in foreign currency (e.g., "50 USD")
2. NOTE: Direct API calls are not available in this environment (see METHODOLOGY.md — No Direct API Calls rule).
   Automated exchange rate lookup is pending API Gateway implementation (see docs/architecture/api-gateway-design.md, planned for v11.0).
3. Ask user: "What is the current {CURRENCY}/ILS exchange rate?"
   - If user provides rate: use it for conversion; note "rate: user-provided" in description
   - If user says "skip" or "I don't know": store in original currency only, mark nis_amount as null, note "rate: pending" in description
4. When rate is available: exchange_rate = user-provided rate
5. nis_amount = floor(amount_agorot * exchange_rate)   [integer math]
6. Store both: amount_agorot (original in minor units), exchange_rate, nis_amount
7. Use nis_amount for all VAT calculations and reports — never recalculate at report time

Confirmation display — currency section: Add to confirmation block when foreign currency:

  Amount:    {X.XX} {CURRENCY} (Rate: {exchange_rate}, NIS: {nis_amount / 100:.2f})

Full eligibility rules: see references/vat-rules.md. Currency handling details: see references/currency.md.

Manual Capture

Triggers: "add expense", "I spent", "log receipt", "track this", "expense this", or any phrase matching the skill description. Also triggers on bare input like "coffee 15 NIS".

Input Grammar

Accept tokens in any order: [vendor] [amount] [currency] [@category] [#client] [biz|personal]

• Amount: numeric token — integer, decimal (45.90), or comma-separated thousands (1,200)
• Currency: NIS, ₪, USD, $, EUR, € — default NIS when absent
• @tag: sets category; must be a canonical name from references/categories.md (food, transport, accommodation, office, software, communications, professional-services, travel, entertainment, education, equipment, other)
• #tag: sets client field
• biz / business / personal / pers: sets type field; default "business" when absent
• Remaining tokens (after extracting amount, currency, @tag, #tag, type keyword) = vendor + description

Parsing Rules

1. Scan for numeric token adjacent to or followed by currency symbol/keyword → extract amount and currency
2. Amounts without currency → assume NIS
3. Negative amounts → reject; prompt "Amounts must be positive. Please re-enter."
4. Comma thousands separator → strip comma before parsing (e.g., "1,200" → 1200)
5. Prefix words like "about", "around", "~" → strip, parse number, append "(approximate)" to description
6. Remaining text after extracting all tagged tokens → vendor; trim whitespace
7. Empty vendor after extraction → prompt "What's the vendor name?"
8. @tag absent → infer category from vendor/description; show inference in confirmation marked [inferred]
9. Ambiguous @tag (e.g., @f) → treat as vendor text; Claude infers category instead
10. Hebrew vendor names → accept as UTF-8, store as-is

Confirmation Display

Show this summary before every save. User must respond before any write occurs.

Ready to save:
  Vendor:    [vendor]
  Amount:    [X.XX NIS]   (or [X.XX USD = Y.YY NIS] for foreign currency)
  Category:  [category]   [inferred] if not from @tag
  Type:      [business|personal]
  Client:    [client or —]
  Date:      [today's date]
  Source:    manual

[Warnings, e.g.: "Amount exceeds 350 NIS — tax invoice (חשבונית מס) may be required"]

Confirm? (yes / edit [field] [value] / cancel)

Edit inline: User says "edit vendor Cafe Aroma" or "edit category office" → update field, re-display summary. Repeat until user says "yes" or "cancel".

After Confirmation

1. Generate ID: count records with same date prefix in receipts.json, increment (EXP-YYYY-MMDD-NNN)
2. Convert amount to agorot (integer): multiply by 100, round — never store floats
3. Calculate VAT: vat_agorot = gross_agorot - floor(gross_agorot / 1.18)
4. Set vat_eligible: true for business, false for personal
5. Set source: "manual", receipt_path: null
6. Execute atomic write (6-step pattern from ## Storage: Atomic Write)
7. Confirm: "Saved: [ID] — [vendor] [amount NIS]"

For foreign currency: ask user for exchange rate (see Multi-currency section) before confirmation, display conversion in summary, store exchange_rate and nis_amount on record.

Edge Cases

Situation	Handling
Missing vendor	Prompt: "What's the vendor name?"
Amount over 350 NIS	Warn in confirmation summary; still allow save
Foreign currency, API unavailable	Prompt: "Enter exchange rate for [currency] → NIS"
Ambiguous type (could be biz or personal)	Show both options in confirmation; ask user to choose
Category not in canonical list	Reject @tag; show list of valid categories

For deeper parsing patterns or additional edge cases, see references/capture-parsing.md (planned for Phase 26+).

Photo OCR Capture

Triggers: User provides a file path to a receipt image, or says "scan this receipt" / "OCR this receipt" with an image path. Supported formats: JPEG, PNG, PDF (single-page).

Step 1 — Read the image

Use the Read tool with the provided file path. The Read tool supports image files natively — Claude processes the image visually. No external OCR service or library is needed. For Hebrew receipts: read Hebrew text as-is; transliterate vendor name to ASCII only if user explicitly prefers. For PDFs: read first page only; note if receipt appears to span multiple pages.

Step 2 — Extract fields with confidence

Extract these fields and assign a confidence level to each:

Field	What to look for
vendor	Merchant name — usually largest text or header on receipt
date	Purchase date — check multiple positions on the receipt
amount	Final grand total — look for "סה"כ לתשלום" or "Total"; NOT a subtotal or line item
currency	Usually NIS/₪ for Israeli receipts; note if ambiguous
description	Summary of items if legible; otherwise "grocery receipt" or similar

Confidence levels:

• clear — text is unambiguous and fully legible
• likely — text partially readable; high confidence in interpretation
• uncertain — text obscured, blurry, or partially cut off; user must confirm before save

Multiple totals visible (subtotal + tax + tip): always pick the final "Total" or "סה"כ לתשלום" line.

Step 3 — Confirmation display with confidence

Show the same format as ## Manual Capture, extended with confidence indicators:

Scanned receipt — please confirm:
  Vendor:    [vendor]      ([confidence])
  Date:      [date]        ([confidence])
  Amount:    [X.XX NIS]    ([confidence])
  Category:  [inferred]    (please confirm)
  Type:      [business|personal]
  Client:    [—]

[List any fields rated "uncertain" as warnings:]
  ⚠ Date could not be read clearly — verify before saving

Confirm? (yes / edit [field] [value] / cancel)

If any field is "uncertain", add a warning line. Do NOT silently save uncertain amounts — always pause for user review. If the image is unreadable (too dark, blurry): respond "Could not extract fields from image. Please try manual entry or retake the photo." and stop. If amount is visible but vendor is not: proceed with confirmation, prompt for vendor name.

Step 4 — Copy image to permanent storage

Before the atomic write, copy the receipt image:

mkdir -p ~/expenses/YYYY/MM/receipts/
cp [source_path] ~/expenses/YYYY/MM/receipts/[ID].[ext]

• YYYY/MM from the expense date
• [ID] is the generated expense ID (e.g., EXP-2026-0320-001)
• [ext] preserves original file extension (jpg, png, pdf)

Set receipt_path in the record to the relative path: "YYYY/MM/receipts/EXP-YYYY-MMDD-NNN.[ext]"

Step 5 — Record creation

• source: "ocr"
• receipt_path: relative path set in Step 4
• All other fields follow the same schema and atomic write pattern as ## Manual Capture
• Apply VAT formula and 350 NIS threshold check as with all captures

For deeper OCR extraction guidance, see references/ocr-guidelines.md (planned for future phases).

Email Capture

Triggers: User pastes email content (HTML or plain text) into the conversation, or provides a file path to a saved .eml or .txt file containing the email.

Step 1 — Strip forwarding headers

Forwarded emails contain metadata before the actual receipt content. Skip past any of these markers before parsing:

• "---------- Forwarded message ----------"
• "Begin forwarded message:" (Apple Mail format)
• Consecutive "From:", "Date:", "Subject:", "To:" lines at the start of a forwarded block

Parse the content AFTER the forwarding header block — not the header itself.

Step 2 — Extract fields

Extract from the email body:

Field	What to look for
vendor	Sender name or company name — From: display name, or header logo/company name in HTML
date	Order/purchase date — look for "Order Date", "Date", "תאריך"; NOT the forwarding date
amount	Final total charge — target labels: "Order Total", "Total", "Grand Total", "Amount Due", "Total Charged", "סה"כ לתשלום", "סכום לחיוב", "סה"כ"; do NOT use subtotals or line item prices
currency	From symbol or code near the total; default NIS if not specified
description	Subject line of the email, or brief item summary (e.g., "Wolt food order", "Amazon order #123-456")

For HTML emails: parse visible text content — focus on table cells and large text amounts; ignore CSS values and image src attributes.

Common vendor patterns:

• Wolt: "Your Wolt order from [restaurant]" → vendor = restaurant name
• Amazon: "Your order of [item]..." → vendor = "Amazon"
• Google/Apple subscriptions: "Your [service] subscription" → vendor = service name
• Israeli receipts (Rami Levy, Shufersal): Hebrew subject, Hebrew total label
• Airline confirmations: vendor = airline name; route as description

Step 3 — Confirmation display

Use the same confirmation format as ## Manual Capture:

Email receipt parsed — please confirm:
  Vendor:    [vendor]
  Date:      [date]
  Amount:    [X.XX NIS]
  Category:  [inferred]  (please confirm)
  Type:      [business|personal]
  Client:    [—]
  Source:    email

Confirm? (yes / edit [field] [value] / cancel)

If vendor or amount could not be extracted, prompt user to fill them before showing confirmation.

Step 4 — Record creation

• source: "email"
• receipt_path: null (no image in this capture mode)
• Apply VAT formula and 350 NIS threshold check as with all captures
• Execute atomic write per ## Storage: Atomic Write

Edge Cases

Situation	Handling
Multiple charges in one email (cart with 3 items)	Extract single final total; list items in description
No recognizable total found	"Could not identify a total amount — please enter amount manually"; switch to manual confirmation with other fields pre-filled
Currency ambiguous (e.g., "$" with Israeli vendor)	Default to USD; show in confirmation for user to correct

Reports

Reading data

• Reports read from ~/expenses/YYYY/MM/receipts.json
• Load multiple months by reading each YYYY/MM/receipts.json in the requested date range
• All monetary values in JSON are integer agorot — divide by 100 for display (e.g., 4590 → 45.90 NIS)
• When a month has no data file, treat as an empty month (no error)

Report 1: Monthly Summary

Trigger: "monthly summary", "expense summary", "how much did I spend [this month / last month / March]"

Output (markdown table in conversation):

## Expenses — [Month YYYY]
Total: X,XXX.XX NIS  (Business: X,XXX.XX | Personal: X,XXX.XX)

Category        | Amount (NIS)
----------------|-------------
food            | 1,250.00
transport       |   340.00
...
Other           |   120.00

Sort categories by total descending. Show personal vs business split in header line.

Report 2: Tax-Ready Excel Export

Trigger: "tax export", "export expenses", "export to Excel", "export [month] expenses" Output: ~/expenses/YYYY/MM/expenses-YYYY-MM.xlsx (openpyxl) See references/reports.md for full column spec and Python script template. After creating the file, confirm: "Saved: ~/expenses/YYYY/MM/expenses-YYYY-MM.xlsx ([N] records)"

Report 3: Category Breakdown

Trigger: "category breakdown", "spending by category", "where did I spend [this month]"

Output (markdown table):

## Category Breakdown — [Month YYYY]
Total: X,XXX.XX NIS

Category        | Amount (NIS) | Share
----------------|-------------|-------
food            |   1,250.00  | 42.3%
transport       |     340.00  | 11.5%
...

Sort descending by amount. Percentages rounded to 1 decimal.

Report 4: Client/Project Billing

Trigger: "client billing", "billing report", "expenses for [client name]", "reimbursable expenses" Input: optionally filter by client name (fuzzy match against client field)

Output (markdown table):

## Billing Report — [Client or All Clients] — [Month YYYY]
(Business expenses only)

Client: Acme Ltd
  Project: website-redesign
    2026-03-15  Taxi to client office   transport    45.00 NIS
    2026-03-18  Client lunch            food        125.00 NIS
  Subtotal: 170.00 NIS

Total: 170.00 NIS

Only include records where type = "business". Group by client → project → date.

No data handling

• Month with zero records: "No expenses found for [month]."
• Filter with no matches: "No [business/client] expenses found for [month]."

Full Excel column spec and Python script template: see references/reports.md.

References

• See references/schema.md for full 17-field JSON schema with field constraints and example record
• See references/categories.md for full category taxonomy with subcategories and Hebrew translations
• See references/vat-rules.md for Israeli VAT formula, invoice type rules, and 350 NIS threshold
• See references/currency.md for multi-currency capture workflow and exchange rate handling
• See references/reports.md for Excel export column spec and Python openpyxl script template