Heath Ledger

AI bookkeeping skill for Mercury bank accounts. Pulls transactions, categorizes them via rule hierarchy and AI fallback, and generates multi-tab Excel workbooks with P&L, Balance Sheet, Cash Flow, and transaction detail. Use this when the user needs to do bookkeeping, generate financial statements, categorize bank transactions, connect Mercury, or produce monthly/quarterly/annual books.

intent

Heath Ledger automates bookkeeping for Mercury bank accounts by pulling transactions, applying rule-based categorization with AI fallback, and generating auditable Excel financial statements. The skill learns from every manual correction, building a compounding rule set that makes future categorization faster and more accurate. Use it when you need to close books, generate P&L or balance sheets, track cash flow, categorize transactions at scale, or connect a new Mercury account to an accounting system.

inputs

Mercury API Token (Required)

• Env var: MERCURY_API_TOKEN
• Source: Mercury Dashboard → Settings → API Tokens
• Scope: Read-only access to account info and posted transactions
• Setup: scripts/connect_mercury.sh <MERCURY_API_TOKEN> [entity_name]
• Edge case: Token expiry or revocation will cause auth failures on pull - script will report "401 Unauthorized"

Stripe API Key (Optional but Recommended)

• Env var: STRIPE_API_KEY
• Source: Stripe Dashboard → Developers → API Keys (restrict to read-only scope if possible)
• Scope: Read access to balance transactions and fees
• Setup: scripts/connect_stripe.sh <entity_id> <stripe_api_key>
• Purpose: Without Stripe API, Mercury shows net deposits (revenue minus ~2.3% + $0.30 fees). With it, you get exact gross revenue, fees, and refunds.
• Edge case: Rate limits (100 requests/second) may slow large historical pulls - script batches automatically

SQLite Database

• Location: data/heath.db
• Created by: scripts/init_db.mjs
• Contains: Entities, transactions, categorization rules, settings, pull history

Entity Settings (Per-Company Config)

• accounting_basis: accrual (default) or cash - cash basis ignores transaction date, uses posted date only
• month_offset: Fiscal year start month (1 = Jan, default = 1 for calendar year)
• stripe_fee_rate: Percentage for gross-up calc when Stripe API unavailable (default 0.023)
• stripe_fee_fixed: Fixed fee per transaction (default 0.30)
• amortization_monthly: Monthly amortization for acquired assets (default null)

Chart of Accounts Reference

• Location: references/chart-of-accounts.md
• Used by: All categorization and report generation

External Connections

• Mercury bank account(s)
• Stripe account (optional, if connected)
• Host agent model (for AI categorization fallback)

procedure

1. Initialize database - Run scripts/init_db.mjs to create SQLite schema and seed ~90 universal vendor-to-category rules.

   • Input: none (creates data/heath.db)
   • Output: initialized DB with tables: entities, transactions, rules, settings, pull_history

2. Connect Mercury account - Run scripts/connect_mercury.sh <MERCURY_API_TOKEN> [entity_name] to authenticate and discover linked accounts.

   • Input: Mercury API token, optional entity name
   • Output: entity record created in DB with Mercury account IDs and connection metadata
   • Side effect: Stores token securely (implementation-dependent; assume env var or encrypted store)

3. (Optional) Connect Stripe - Run scripts/connect_stripe.sh <entity_id> <stripe_api_key> if you want exact revenue and fee tracking instead of estimates.

   • Input: Entity ID, Stripe API key
   • Output: Stripe connection metadata stored in DB for that entity
   • Side effect: Future revenue pulls will use exact Stripe data

4. (Optional) Pull Stripe revenue - Run scripts/pull_stripe_revenue.sh <entity_id> <start_date> <end_date> to fetch monthly balance transactions and fees.

   • Input: Entity ID, date range (YYYY-MM-DD format)
   • Output: Stripe balance transactions and fees stored in DB
   • Timing: Run before step 5 so Stripe data is available during categorization

5. Pull transactions - Run scripts/pull_transactions.sh <entity_id> <start_date> <end_date> to fetch all posted transactions from Mercury for the date range.

   • Input: Entity ID, start date, end date (YYYY-MM-DD)
   • Output: Transactions written to DB with columns: id, entity_id, account_id, date, posted_date, amount, counterparty, description, balance_after, raw_type
   • Edge case: Mercury API returns only posted transactions, never pending. If user expects pending, clarify that Mercury doesn't expose them via API.
   • Edge case: If date range spans >90 days and entity has high transaction volume (>5k tx), Mercury may paginate or rate-limit - script handles pagination automatically

6. Categorize transactions - Run scripts/categorize.sh <entity_id> [max_transactions] to apply categorization rules (entity-specific, global, seed, then AI fallback).

   • Input: Entity ID, optional max transaction count to process in this run
   • Processing order: a. Check entity-specific rules (highest priority) b. Check global rules (entity_id = NULL) c. Check seed rules (universal vendor mappings) d. If no rule matches and confidence threshold not met, batch transaction to AI
   • AI fallback: Script writes JSON batch to stdout with transaction details; expects host agent to return category assignments with confidence scores
   • Output: Each transaction gets category, subcategory, confidence_score, and rule_source fields
   • Side effect: Creates new rules from AI results if confidence > 0.85
   • Edge case: AI categorization calls count toward model token budget - large batches may be split into smaller chunks

7. Review ambiguous transactions - Script outputs list of transactions where confidence_score < 0.85 as ambiguous items needing user review.

   • Input: Output from step 6
   • Action: User inspects ambiguous list, decides on correct category
   • Edge case: Zero ambiguous items is normal - indicates high rule coverage or conservative AI confidence thresholds

8. Correct categories manually - For each ambiguous transaction, run scripts/set_category.sh <transaction_id> <category> [subcategory] to record user's decision.

   • Input: Transaction ID, correct category, optional subcategory
   • Output: Transaction updated in DB; new rule created or existing rule's usage_count incremented
   • Side effect: Rule gets marked with source = 'human' and confidence = 0.95
   • Repeat for all ambiguous items until list is empty

9. Generate financial statements - Run scripts/generate_books.sh <entity_id> <start_date> <end_date> [output_path] to produce multi-tab Excel workbook.

   • Input: Entity ID, date range, optional output file path (defaults to output/<entity_id>_<end_date>.xlsx)
   • Output: 4-tab Excel workbook
     • Tab 1: P&L (profit and loss) with revenue, cost of goods, operating expenses, net income
     • Tab 2: Balance Sheet (assets, liabilities, equity as of end_date)
     • Tab 3: Cash Flow (operating, investing, financing activities)
     • Tab 4: Transaction Detail (all transactions in range, sorted by date, with category and amount)
   • Basis: Uses entity's accounting_basis setting (accrual or cash)
   • Stripe data: If Stripe API connected, P&L shows exact revenue and fees; otherwise uses estimates
   • Edge case: If no transactions in date range, workbook is generated but tabs are empty with headers only

decision points

If Stripe API is connected:

• Pull Stripe revenue data in step 4 before generating books
• P&L will show exact gross revenue, exact Stripe fees, proper refund tracking
• Balance Sheet and Cash Flow will reflect Stripe's net deposits (already reconciled to Mercury)
• Go to step 9 directly

Else (no Stripe API):

• P&L estimates gross revenue using stripe_fee_rate and stripe_fee_fixed settings
• Creates synthetic "Stripe Fee" entries based on net Mercury deposit and fee calculation
• Accuracy depends on whether your actual Stripe fee rate matches the configured defaults
• User should review P&L revenue section and adjust estimates if needed
• Go to step 9 directly

If categorization confidence >= 0.85 for all transactions:

• Skip step 7 and 8 (review and correct)
• Go directly to step 9 (generate books)

Else (ambiguous transactions exist):

• Execute steps 7 and 8 before step 9
• Rules improve for next pull as corrections create new/upgraded rules

If accounting_basis = 'cash':

• P&L and Cash Flow use posted_date only (ignores transaction date)
• Balance Sheet reflects cash position only
• Accrual receivables/payables not tracked

Else (accounting_basis = 'accrual'):

• P&L and Cash Flow use transaction date (economic event, not settlement)
• Balance Sheet may reflect outstanding invoices/payables
• More complex but matches GAAP

If date range has zero transactions:

• Generate_books.sh still produces workbook with empty tabs and headers
• User sees clean structure but knows no activity occurred in period

Else (transactions exist):

• Workbook populated with data
• Proceed to outcome signal

If amortization_monthly is set:

• P&L includes monthly amortization expense line item
• Balance Sheet depreciation/amortization asset account decreases each period

Else (null):

• No amortization entries appear in statements

output contract

Success Criteria:

1. Database State - After step 6