jaz-cli 2.0.0

package/assets/skills/conversion/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: conversion
+version: 2.0.0
+description: Accounting data conversion skill — migrates customer data from Xero, QuickBooks, Sage, and Excel exports to Jaz. Covers full and quick conversion workflows, Excel parsing, CoA/contact/tax mapping, clearing accounts, TTB, and TB verification.
+---
+
+# Jaz Conversion Skill
+
+You are performing an **accounting data conversion** — migrating a customer's financial data from their previous accounting software (Xero, QuickBooks, Sage, or Excel-based systems) into Jaz.
+
+**This skill provides conversion domain knowledge. For API details (field names, endpoints, gotchas), load the `jaz-api` skill alongside this one.**
+
+## When to Use This Skill
+
+- Analyzing customer-provided Excel/CSV files for conversion
+- Mapping source Chart of Accounts, contacts, tax codes, or items to Jaz
+- Creating conversion transactions (invoices, bills, journals)
+- Building or reviewing TTB (Transfer Trial Balance) entries
+- Verifying post-conversion Trial Balance accuracy
+- Troubleshooting TB mismatches after a conversion
+
+## Two Conversion Types
+
+Both types use the **same pipeline** — only the scope (which entity types) differs.
+
+### Quick Conversion (Option 2 — recommended starting point)
+- **Scope:** Open AR/AP at FYE + TTB opening balances
+- **Creates:** CoA, contacts, currencies, tax mapping, conversion invoices/bills, TTB journal, lock date
+- **When:** Customer wants to start fresh on Jaz with correct opening balances
+- **Accuracy check:** TB at FYE must match between source and Jaz
+- **See:** `references/option2-quick.md`
+
+### Full Conversion (Option 1)
+- **Scope:** ALL transactions for FY + FY-1 (complete history)
+- **Creates:** Everything in Quick + items, detailed invoices, bills, payments, journals, credit notes, cash-in/out/transfers, bank records, fixed assets
+- **When:** Customer needs full audit trail preserved
+- **Accuracy check:** TB at multiple dates, plus detailed ledger comparison
+- **See:** `references/option1-full.md`
+
+## Conversion Pipeline
+
+Every conversion follows this pipeline. Steps 1-3 use the parser + AI. Steps 4-8 use the jaz-api skill.
+
+### Step 1: Intake
+Receive customer files. Organize by type. Expect messy Excel files with grouped sections, merged cells, subtotals, and inconsistent formatting.
+
+**Common file types:**
+- Chart of Accounts (CoA export)
+- Trial Balance (TB at FYE)
+- AR Aging / AP Aging (outstanding receivables/payables at FYE)
+- Contact list (customers and suppliers)
+- Tax profile list
+- Exchange rates (closing rates at FYE)
+- General Ledger detail (for Full only)
+- Invoice/bill detail (for Full only)
+
+### Step 2: Parse (3-pass approach)
+See `references/file-analysis.md` for parsing guidance and `references/file-types.md` for the comprehensive file type catalog (22 types across all source systems).
+
+**Pass A — Raw dump:** Run the parser (`parseFile()`) to extract all cells + merge metadata from Excel files. The parser handles merged cell propagation automatically.
+
+**Pass B — AI structure detection:** Read the raw JSON dump and identify:
+- Where are the data tables? (header row + data rows)
+- What are subtotal/total rows? (exclude from data extraction)
+- What is metadata vs actual data? (company name, report date = metadata)
+- Are there multiple data frames per sheet? (some exports have AR and AP on same sheet)
+
+**Pass C — AI classification:** For each identified data table:
+- What type of data is this? (TB, AR aging, AP aging, CoA, contacts, etc.)
+- What are the column headers mapped to? (Account Code, Account Name, Debit, Credit, etc.)
+- What date range does it cover?
+- What currency is it in?
+
+### Step 3: Map
+See `references/mapping-rules.md` for detailed rules.
+
+For each entity type, map source data → Jaz entities:
+- **CoA:** Match by code AND name. Fresh org = replace non-system accounts. Existing org = fuzzy match.
+- **Contacts:** Match by name. Create if not found.
+- **Tax:** Read-only in Jaz — discover existing profiles, match source codes to Jaz tax types.
+- **Currencies:** Enable required currencies, set FYE exchange rates.
+
+Assign confidence scores (high/medium/low) to each mapping. Flag low-confidence for human review.
+
+### Step 4: Transform
+Convert mapped data into Jaz API payloads. Different per conversion type:
+- **Quick:** See `references/option2-quick.md` — clearing account pattern
+- **Full:** See `references/option1-full.md` — detailed transaction creation
+
+### Step 5: Dry Run
+Before any API calls, present a summary for human review:
+- Entity counts (how many of each type will be created)
+- CoA mapping table (source → Jaz, with confidence)
+- Contact list to be created
+- For Quick: each conversion invoice/bill (contact, amount, currency)
+- Edge cases flagged (FX, unmapped accounts, partial payments)
+
+**Do NOT project a Trial Balance.** TB comes from the ledger after execution. Projecting it is unreliable and misleading.
+
+### Step 6: Execute
+Create records via Jaz API. Follow the dependency order:
+1. Currencies (must exist before CoA with foreign currency)
+2. CoA (must exist before transactions reference accounts)
+3. Contacts (must exist before invoices/bills reference them)
+4. Tax profiles (read-only — just discover and map)
+5. Transactions (invoices, bills, journals)
+6. Payments (must reference existing invoices/bills)
+
+### Step 7: Verify
+After execution, pull the Trial Balance from Jaz and compare against the source TB.
+See `references/verification.md` for the full checklist format.
+
+### Step 8: Triage (if TB doesn't match)
+If TB doesn't match, identify the discrepancy:
+- Missing accounts? → Create them + journal adjustment
+- Rounding drift? → Small adjustment journal
+- FX differences? → Check rates, may need unrealized gain/loss journal
+- Missed transactions? → Create them
+- Re-verify after each fix until TB matches
+
+## Critical Rules
+
+1. **TTB is a regular journal entry** — Jaz's TTB module is not yet on the API. Create via `POST /journals`. Lock date is set separately via CoA API.
+2. **Fixed asset transfers use `POST /api/v1/transfer-fixed-assets`** — not the "new asset" endpoint. Preserves accumulated depreciation.
+3. **Clearing accounts must net to zero** — if they don't, something was missed in the conversion.
+4. **Never project TB before execution** — verify AFTER, then triage.
+5. **FYE exchange rates + original dates** — Quick conversion uses original dates (for aging) but explicit FYE rate via `currency: { sourceCurrency, exchangeRate }` on every FX transaction. Prior UGL is in the TTB; explicit rate ensures zero UGL in Jaz. See `references/edge-cases.md`.
+6. **System-generated CoA accounts cannot be deleted** — discover them via API before attempting a wipe-and-replace.
+7. **100% accuracy is required** — customer's accountant signs off on TB match. No rounding errors, no missing balances.
+8. **Always load `jaz-api` skill alongside this one** — this skill has conversion domain knowledge, `jaz-api` has API field names, endpoints, and gotchas.

package/assets/skills/conversion/references/edge-cases.md

@@ -0,0 +1,174 @@
+# Edge Cases — FX, Clearing Accounts, Rounding, and More
+
+## Foreign Exchange (FX)
+
+### Setting Org-Level FYE Rates
+Enable currencies and set FYE closing rates before creating any FX transactions:
+
+```
+PUT /api/v1/organization/currencies           // Enable currency
+{ "currencies": ["USD"] }
+
+POST /api/v1/organization-currencies/USD/rates  // Set FYE rate
+{ "rate": 1.35, "rateApplicableFrom": "2024-12-31" }
+```
+
+**Rate direction:** Jaz uses `functionalToSource` — how many functional currency units per 1 source currency unit. If base = SGD and "1 USD = 1.35 SGD", then `rate = 1.35`.
+
+**CRITICAL:** `currencyCode: "USD"` (string) is **silently ignored** by the API — it creates the transaction in base currency. You MUST use the `currency` object form.
+
+### Quick Conversion — Explicit FYE Rate on Transactions
+
+FX conversion transactions use **original dates** (for aging) but an **explicit FYE exchange rate** (for zero UGL):
+
+```json
+{
+  "valueDate": "2024-06-15",
+  "dueDate": "2024-07-15",
+  "currency": {
+    "sourceCurrency": "USD",
+    "exchangeRate": 1.35
+  }
+}
+```
+
+The `exchangeRate` field overrides Jaz's rate auto-fetch. This is essential because:
+
+1. **Prior UGL is in the TTB:** The old platform already computed unrealized FX gains/losses up to FYE. That UGL sits in the TTB journal (Unrealized FX Gain/Loss account balance). If conversion invoices used a different rate, Jaz would compute additional UGL — doubling up.
+
+2. **Zero UGL on day 1:** FYE rate = transferred transaction rate → Jaz sees zero unrealized gain/loss from these conversion invoices/bills.
+
+3. **Correct future RGL:** When a payment is recorded against a conversion invoice, Jaz computes realized gain/loss against the FYE rate — which is correct. The balance was already marked-to-market at FYE by the prior platform.
+
+4. **Correct aging:** Original dates preserve the aging schedule (30/60/90/120+ buckets) so the AR/AP aging report in Jaz matches the source.
+
+### Full Conversion — Original Transaction Rates
+
+Full conversion uses the **original exchange rate** from each transaction (the rate at the time the invoice/bill was created). If the source provides per-transaction rates, pass them via `exchangeRate`. If not, Jaz auto-fetches ECB rates via the Frankfurter provider based on `valueDate`.
+
+### Unrealized FX Gains/Losses — Quick vs. Full
+
+**Quick Conversion:** UGL from the prior platform is captured in the TTB journal. Conversion invoices/bills are recorded at FYE rate with explicit `exchangeRate`, producing zero UGL in Jaz. No separate UGL journals are needed.
+
+**Full Conversion:** Replicate any unrealized FX revaluation journals from the source system as manual journals in Jaz, if they fall within the conversion period. These preserve the historical UGL trail.
+
+## Clearing Account Mechanics
+
+### How Clearing Accounts Work
+
+**After Phase 2 (conversion invoices/bills):**
+- AR Clearing has a CREDIT balance (from invoice line items)
+- AP Clearing has a DEBIT balance (from bill line items)
+
+**After Phase 3 (TTB journal):**
+- TTB debits AR Clearing (for the AR balance amount)
+- TTB credits AP Clearing (for the AP balance amount)
+- Both clearing accounts should now be **exactly zero**
+
+### Debugging Non-Zero Clearing Accounts
+
+If AR Clearing ≠ 0:
+```
+AR Clearing balance = (TTB AR debit) - (sum of all conversion invoice amounts)
+```
+- **Positive balance:** TTB AR amount > sum of invoices → missing invoices or wrong amounts
+- **Negative balance:** Sum of invoices > TTB AR amount → extra invoices or wrong TB amount
+
+Same logic applies for AP Clearing.
+
+### Common Causes
+1. **Rounding in FX conversions** — functional currency amounts may differ by $0.01-0.02
+2. **AR aging doesn't match TB** — some aging reports exclude credit balances or include disputed amounts
+3. **Missing invoices/bills** — some entries in the aging report were missed during creation
+4. **Different FX rates** — invoice created with a different rate than TTB (should not happen if explicit `exchangeRate` is used on FX transactions)
+
+### Fix
+Create a small adjustment journal to bring the clearing account to zero. Document the reason (e.g., "FX rounding adjustment — $0.02").
+
+## Rounding
+
+### The $0.01 Problem
+Accounting systems often produce rounding differences when converting between currencies. A source TB may show $1,234.57 but the sum of individual conversion invoices totals $1,234.56.
+
+**Rules:**
+1. Always use the source's exact amounts — never round or truncate
+2. If the source has amounts to more than 2 decimal places, use them as-is (Jaz supports up to 6 decimals on unit prices)
+3. If a rounding difference exists after all transactions are created, add a small adjustment journal
+
+### Rounding in Tax Calculations
+If the source calculates tax differently from Jaz (e.g., tax per line item vs tax on total), small differences may arise. Create an adjustment journal if needed.
+
+## Partial Payments in AR/AP Aging
+
+### Quick Conversion
+The AR/AP Aging report shows **outstanding amounts only**. Partial payments are already factored in — the aging shows what's still owed.
+
+Create conversion invoices/bills for the outstanding amount, not the original amount. Historical payments are not relevant.
+
+### Full Conversion
+Each payment must be linked to its invoice/bill. If a single payment covers multiple invoices, create separate payment records:
+
+```
+POST /api/v1/invoices/<invoice1>/payments
+{ "payments": [{ "paymentAmount": 500, "transactionAmount": 500, ... }] }
+
+POST /api/v1/invoices/<invoice2>/payments
+{ "payments": [{ "paymentAmount": 300, "transactionAmount": 300, ... }] }
+```
+
+## Credit Balances
+
+### Negative AR (Customer Credit Balance)
+If the AR Aging shows a negative amount for a customer, they have a credit balance (overpayment or unapplied credit note).
+
+**Options:**
+1. Create a customer credit note for the amount
+2. Create a conversion invoice with negative amount (if the API allows)
+3. Include in the TTB journal as a credit to AR
+
+### Negative AP (Supplier Credit Balance)
+Same logic — create a supplier credit note or include in TTB.
+
+## System-Generated Accounts
+
+When doing a CoA wipe-and-replace on a fresh org:
+
+### Accounts That Cannot Be Deleted
+- **Retained Earnings** — system-controlled, used for year-end close
+- **Unrealized Currency Gain/Loss** — system auto-creates for FX revaluation
+- **Rounding** — system account for rounding adjustments
+- **Bank accounts linked to payment methods** — must unlink first
+
+### Discovery
+```
+GET /api/v1/accounts
+```
+Check for `isSystemGenerated: true` or equivalent flag. These must be preserved.
+
+### Strategy
+1. Map source accounts to system accounts where possible (e.g., source "Retained Earnings" → Jaz's system "Retained Earnings")
+2. Skip deletion of system accounts
+3. Create only the accounts that don't already exist
+
+## Void and Rollback
+
+If a conversion goes wrong mid-execution:
+
+### For Invoices/Bills
+- `POST /api/v1/invoices/<id>/void` — voids the document (cannot be undone)
+- `DELETE /api/v1/invoices/<id>` — deletes draft invoices only
+
+### For Journals
+- `DELETE /api/v1/journals/<id>` — deletes the journal entry
+
+### For Contacts/Items
+- `DELETE /api/v1/contacts/<id>` — only if no transactions reference them
+- `DELETE /api/v1/items/<id>` — only if no transactions reference them
+
+### For CoA
+- `DELETE /api/v1/accounts/<id>` — only if no transactions reference them
+
+### Rollback Strategy
+1. Delete in reverse order of creation (payments → transactions → contacts → CoA)
+2. Some entities may be undeletable if they have dependencies
+3. In worst case, voiding is always available for transactions

package/assets/skills/conversion/references/file-analysis.md

@@ -0,0 +1,120 @@
+# Analyzing Excel Accounting Reports
+
+## The Challenge
+
+Accounting exports from Xero, QuickBooks, Sage, and generic Excel are messy:
+- **Merged cells** — headers span multiple columns, category labels span rows
+- **Grouped sections** — rows grouped by account type, customer, date range
+- **Subtotals everywhere** — per group, per page, grand totals
+- **Metadata rows** — company name, report title, date range, print date (not data)
+- **Multiple data frames** — some sheets have AR and AP in different sections
+- **Inconsistent formatting** — bold totals, blank separator rows, indented sub-accounts
+
+The parser library handles raw cell extraction and merged cell propagation. **You** do the intelligent work of understanding the structure.
+
+## 3-Pass Approach
+
+### Pass A: Raw Dump
+Run the parser to get `ParsedFile` with cells + merge metadata.
+
+When reviewing the raw output, note:
+- **Row 0-5:** Usually metadata (company name, report title, date generated)
+- **First row with many populated cells:** Likely the header row
+- **Rows with cells only in column 0-1:** Category labels or group headers
+- **Rows where numeric columns sum to a group total:** Subtotal rows
+- **Blank rows:** Section separators
+
+### Pass B: Structure Detection
+For each sheet, identify:
+
+1. **Header row(s):** The row(s) containing column labels. Look for:
+   - Row with the most populated cells
+   - Keywords: "Account", "Code", "Name", "Debit", "Credit", "Balance", "Amount", "Contact", "Date", "Reference"
+   - Sometimes headers span 2 rows (main header + sub-header)
+
+2. **Data rows:** Rows between header and first total/blank section. Characteristics:
+   - Have values in the same columns as headers
+   - Account codes are numeric or alphanumeric (e.g., "1000", "4-1000", "GST7")
+   - Amounts are numeric (possibly with accounting formatting: parentheses for negatives)
+
+3. **Subtotal/total rows:** Rows to EXCLUDE. Characteristics:
+   - Contain keywords: "Total", "Sub-total", "Grand Total", "Net", "Balance"
+   - Have values only in amount columns (not in code/name columns)
+   - Often preceded or followed by blank rows
+   - In merged cell sheets, the label cell often spans multiple columns
+
+4. **Group headers:** Category rows (e.g., "Current Assets", "Revenue"). Characteristics:
+   - Text in column 0-1 only, no amounts
+   - Often merged across columns
+   - Followed by indented data rows
+
+5. **Multiple data frames:** Some exports put different reports on the same sheet:
+   - Look for a second header row mid-sheet
+   - Blank rows or merged section titles between frames
+   - Different column structures in different sections
+
+### Pass C: Classification
+For each identified data table, determine the type. See `references/file-types.md` for the comprehensive catalog of all 22 file types with source-system-specific patterns.
+
+Quick reference for the most common types:
+
+| Type | Key Indicators |
+|------|---------------|
+| **Trial Balance** | "Debit" + "Credit" columns OR "Balance" column. Account codes + names. No dates per row. |
+| **AR Aging Detail** | Customer names. Aging buckets (Current/30/60/90+). Per-invoice rows. |
+| **AP Aging Detail** | Supplier names. Same aging bucket pattern as AR. |
+| **Chart of Accounts** | Account code + name + type/classification. No balances or dates. |
+| **General Ledger Detail** | Dates + account + source module + description + debit/credit per transaction. Grouped by account. |
+| **Contact List** | Names + addresses/phones/emails. No financial data. |
+| **GL Subledger** | Single control account detail (AR/AP/Intercompany). Sheet within multi-report workbook. |
+| **Platform Export (Jaz)** | CSV with UUIDs, `resource_id`, `jaz.ai` emails. **SKIP — not source data.** |
+
+## Common Source System Patterns
+
+### Xero Exports
+- Clean CSV/Excel exports with consistent headers
+- Account codes are numeric (e.g., "200", "400")
+- Tax codes: "GST on Income", "GST on Expenses", "BAS Excluded", "GST Free"
+- Contact type clearly labeled as "Customer" or "Supplier"
+
+### QuickBooks Exports
+- Often have grouped/indented accounts (sub-accounts indented under parents)
+- May use "Total <category>" rows extensively
+- Account numbers may be optional (some QB setups don't use them)
+- Tax codes vary by region
+
+### Sage Exports
+- Typically clean tabular exports
+- Account codes often in "XXXX" format (4 digits)
+- May include "Nominal Code" + "Nominal Name" columns
+- Tax codes: "T0" (Zero Rated), "T1" (Standard Rate), etc.
+
+### Generic Excel (manual)
+- Most unpredictable format
+- May have custom formulas, conditional formatting
+- Watch for:
+  - Hidden rows/columns (SheetJS extracts these)
+  - Grouped/outlined rows (collapsed sections)
+  - Cross-sheet references (formulas referencing other sheets)
+
+## Amount Parsing
+
+Accounting exports use various number formats:
+- `1,234.56` — standard with comma grouping
+- `(1,234.56)` — parentheses = negative (accounting convention)
+- `-1,234.56` — negative sign
+- `1234.56` — no grouping
+- `$1,234.56` — with currency symbol (strip the symbol)
+- Blank or `-` — zero / no value
+
+The CSV parser handles these automatically. For Excel files, SheetJS provides the numeric value directly.
+
+## Confidence Scoring for AI Classification
+
+When analyzing a sheet, assign confidence:
+
+- **High (>80%):** Headers clearly match a known type, data structure is consistent
+- **Medium (50-80%):** Partial match — some expected columns present, some missing or renamed
+- **Low (<50%):** Ambiguous — could be multiple types, or unknown format
+
+Flag medium and low confidence for human review before proceeding.