jaz-cli 2.7.0 → 2.8.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-version: 2.7.0
+version: 2.8.0
 description: Complete reference for the Jaz/Juan REST API — the accounting platform backend. Use this skill whenever building, modifying, debugging, or extending any code that calls the API — including API clients, integrations, data seeding, test data, or new endpoint work. Contains every field name, response shape, error, gotcha, and edge case discovered through live production testing.
 license: MIT
 compatibility: Requires Jaz/Juan API key (x-jk-api-key header). Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conversion
-version: 2.7.0
+version: 2.8.0
 description: Accounting data conversion skill — migrates customer data from Xero, QuickBooks, Sage, MYOB, and Excel exports to Jaz. Covers config, quick, and full conversion workflows, Excel parsing, CoA/contact/tax/items mapping, clearing accounts, TTB, and TB verification.
 ---
 

package/assets/skills/jobs/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: jobs
+version: 2.8.0
+description: 10 accounting jobs for SMB bookkeepers and accountants — month-end, quarter-end, and year-end close playbooks plus 7 ad-hoc operational jobs (bank recon, GST/VAT filing, payment runs, credit control, supplier recon, audit prep, fixed asset review). Each job is a step-by-step blueprint with API calls, recipe references, calculator commands, and verification checks. Paired with an interactive CLI blueprint generator (jaz jobs).
+license: MIT
+compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill. For individual transaction patterns, load the transaction-recipes skill.
+---
+
+# Jobs Skill
+
+You are helping an **SMB accountant or bookkeeper** complete recurring accounting tasks in Jaz — period-end closes, bank reconciliation, tax filing, payment processing, and operational reviews. These are the real jobs that keep the books accurate and the business compliant.
+
+**Jobs combine recipes, calculators, and API calls into complete business processes.** If recipes are ingredients, jobs are the meal.
+
+## When to Use This Skill
+
+- Closing the books for a month, quarter, or year
+- Catching up on bank reconciliation
+- Preparing GST/VAT returns for filing
+- Running a payment batch to clear outstanding bills
+- Chasing overdue invoices (credit control)
+- Reconciling supplier statements against AP ledger
+- Preparing for an audit or tax filing
+- Reviewing the fixed asset register
+
+## Job Catalog
+
+### Period-Close Jobs (Layered)
+
+Period-close jobs build on each other. Quarter = month + extras. Year = quarter + extras. Each level runs **standalone by default** (includes all steps from lower levels). Use `--incremental` to generate only the extras.
+
+| Job | CLI Command | Description |
+|-----|-------------|-------------|
+| **Month-End Close** | `jaz jobs month-end --period YYYY-MM` | 5 phases: pre-close prep, accruals, valuations, verification, lock. The foundation. |
+| **Quarter-End Close** | `jaz jobs quarter-end --period YYYY-QN` | Month-end for each month + GST/VAT, ECL review, bonus accruals, intercompany, provisions. |
+| **Year-End Close** | `jaz jobs year-end --period YYYY` | Quarter-end for each quarter + true-ups, dividends, CYE rollover, audit prep, final lock. |
+
+### Ad-Hoc Jobs
+
+| Job | CLI Command | Description |
+|-----|-------------|-------------|
+| **Bank Recon** | `jaz jobs bank-recon` | Clear unreconciled items: match, categorize, resolve. |
+| **GST/VAT Filing** | `jaz jobs gst-vat --period YYYY-QN` | Tax ledger review, discrepancy check, filing summary. |
+| **Payment Run** | `jaz jobs payment-run` | Select outstanding bills by due date, process payments. |
+| **Credit Control** | `jaz jobs credit-control` | AR aging review, overdue chase list, bad debt assessment. |
+| **Supplier Recon** | `jaz jobs supplier-recon` | AP vs supplier statement, identify mismatches. |
+| **Audit Preparation** | `jaz jobs audit-prep --period YYYY` | Compile reports, schedules, reconciliations for auditor/tax. |
+| **FA Review** | `jaz jobs fa-review` | Fixed asset register review, disposal/write-off processing. |
+
+## How Jobs Work
+
+Each job produces a **blueprint** — a phased checklist of steps, each annotated with:
+
+- **API call** — the exact endpoint + request body to execute the step
+- **Recipe reference** — link to the transaction-recipes skill for complex accounting patterns
+- **Calculator command** — `jaz calc` command for financial calculations
+- **Verification check** — how to confirm the step was completed correctly
+- **Conditional flag** — steps that only apply in certain situations (e.g., "only if multi-currency org")
+
+**For AI agents:** Read the blueprint and execute each step using the jaz-api skill for payloads.
+**For developers:** Use `--json` output to build automation pipelines.
+**For accountants:** Use the formatted checklist to work through the close systematically.
+
+## CLI Usage
+
+```bash
+# Period-close (standalone = full plan, --incremental = extras only)
+jaz jobs month-end --period 2025-01 [--currency SGD] [--json]
+jaz jobs quarter-end --period 2025-Q1 [--incremental] [--json]
+jaz jobs year-end --period 2025 [--incremental] [--json]
+
+# Ad-hoc
+jaz jobs bank-recon [--account "DBS Current"] [--period 2025-01] [--json]
+jaz jobs gst-vat --period 2025-Q1 [--json]
+jaz jobs payment-run [--due-before 2025-02-28] [--json]
+jaz jobs credit-control [--overdue-days 30] [--json]
+jaz jobs supplier-recon [--supplier "Acme Corp"] [--period 2025-01] [--json]
+jaz jobs audit-prep --period 2025 [--json]
+jaz jobs fa-review [--json]
+```
+
+## Relationship to Other Skills
+
+| Skill | Role |
+|-------|------|
+| **api** | Provides the exact API payloads for each step (field names, gotchas, error handling) |
+| **transaction-recipes** | Provides the accounting patterns for complex steps (accruals, FX reval, ECL, etc.) |
+| **jobs** (this skill) | Combines recipes + API into sequenced, verifiable business processes |
+
+**Load all three skills together** for the complete picture. Jobs reference recipes by name — an AI agent should read the referenced recipe for implementation details.
+
+## Supporting Files
+
+- **[references/building-blocks.md](./references/building-blocks.md)** — Shared concepts: accounting periods, lock dates, period verification, conventions
+- **[references/month-end-close.md](./references/month-end-close.md)** — Month-end close: 5 phases, ~18 steps
+- **[references/quarter-end-close.md](./references/quarter-end-close.md)** — Quarter-end close: monthly + quarterly extras
+- **[references/year-end-close.md](./references/year-end-close.md)** — Year-end close: quarterly + annual extras
+- **[references/bank-recon.md](./references/bank-recon.md)** — Bank reconciliation catch-up
+- **[references/gst-vat-filing.md](./references/gst-vat-filing.md)** — GST/VAT filing preparation
+- **[references/payment-run.md](./references/payment-run.md)** — Payment run (bulk bill payments)
+- **[references/credit-control.md](./references/credit-control.md)** — Credit control / AR chase
+- **[references/supplier-recon.md](./references/supplier-recon.md)** — Supplier statement reconciliation
+- **[references/audit-prep.md](./references/audit-prep.md)** — Audit preparation pack
+- **[references/fa-review.md](./references/fa-review.md)** — Fixed asset register review

package/assets/skills/jobs/references/audit-prep.md

@@ -0,0 +1,319 @@
+# Audit Preparation
+
+Compile the complete report pack, supporting schedules, and reconciliations that an auditor or tax agent needs. For most SMBs, this is an annual exercise — either for the statutory audit (if required) or for the annual tax filing with IRAS (SG) or BIR (PH).
+
+**CLI:** `jaz jobs audit-prep --period 2025 [--json]`
+
+---
+
+## Who Needs This
+
+| Situation | SG | PH |
+|-----------|----|----|
+| **Statutory audit required** | Companies with revenue > S$10M, assets > S$10M, or employees > 50 | All stock corporations, companies with paid-up capital > PHP 50K |
+| **Tax filing (no audit)** | All companies file Form C/C-S with IRAS | All companies file ITR with BIR |
+| **Compilation by accountant** | Small exempt private companies — no audit but accountant prepares financial statements | N/A |
+
+Even if you're a small exempt company not requiring an audit, your external accountant or tax agent needs the same reports to prepare your financial statements and tax return. This job produces the full pack.
+
+---
+
+## Phase 1: Core Financial Reports
+
+Generate the three primary financial statements. These form the backbone of any audit or tax filing.
+
+### Step 1: Trial Balance
+
+The master reconciliation tool. Everything else derives from this.
+
+```
+POST /api/v1/generate-reports/trial-balance
+{ "startDate": "2025-01-01", "endDate": "2025-12-31" }
+```
+
+**What the auditor checks:** Debits = Credits (always). Any imbalance indicates a system error.
+
+### Step 2: Profit & Loss Statement
+
+```
+POST /api/v1/generate-reports/profit-and-loss
+{ "primarySnapshotDate": "2025-12-31", "secondarySnapshotDate": "2025-01-01" }
+```
+
+**Comparative:** If the auditor needs prior year comparison:
+
+```
+POST /api/v1/generate-reports/profit-and-loss
+{ "primarySnapshotDate": "2024-12-31", "secondarySnapshotDate": "2024-01-01" }
+```
+
+### Step 3: Balance Sheet
+
+```
+POST /api/v1/generate-reports/balance-sheet
+{ "primarySnapshotDate": "2025-12-31" }
+```
+
+**Key check:** Assets = Liabilities + Equity.
+
+---
+
+## Phase 2: Supporting Ledgers
+
+Detailed transaction-level data behind the summary reports.
+
+### Step 4: General Ledger — grouped by account
+
+```
+POST /api/v1/generate-reports/general-ledger
+{ "startDate": "2025-01-01", "endDate": "2025-12-31", "groupBy": "ACCOUNT" }
+```
+
+This is the auditor's primary working document. Every transaction, grouped by CoA account, with opening balance, movements, and closing balance.
+
+### Step 5: Cashflow Statement
+
+```
+POST /api/v1/generate-reports/cashflow
+{ "primaryStartDate": "2025-01-01", "primaryEndDate": "2025-12-31" }
+```
+
+Classifies cash movements into Operating, Investing, and Financing activities.
+
+### Step 6: Equity Movement
+
+```
+POST /api/v1/generate-reports/equity-movement
+{ "primarySnapshotStartDate": "2025-01-01", "primarySnapshotEndDate": "2025-12-31" }
+```
+
+Shows opening equity, net profit, dividends, and other movements during the year.
+
+---
+
+## Phase 3: Aging Reports
+
+### Step 7: AR Aging (Accounts Receivable)
+
+```
+POST /api/v1/generate-reports/ar-report
+{ "endDate": "2025-12-31" }
+```
+
+**Auditor use:** Tests recoverability of receivables. Aging > 90 days triggers bad debt assessment. The AR total MUST tie to the Accounts Receivable balance on the trial balance.
+
+### Step 8: AP Aging (Accounts Payable)
+
+```
+POST /api/v1/generate-reports/ap-report
+{ "endDate": "2025-12-31" }
+```
+
+**Auditor use:** Completeness assertion — are all liabilities recorded? The AP total MUST tie to the Accounts Payable balance on the trial balance.
+
+---
+
+## Phase 4: Bank and Cash
+
+### Step 9: Bank Reconciliation Summary
+
+```
+POST /api/v1/generate-reports/bank-reconciliation-summary
+{ "primarySnapshotDate": "2025-12-31" }
+```
+
+**This is non-negotiable for auditors.** The bank recon proves that the cash balance per books matches the bank statement. Any unreconciled items at year-end must be explained.
+
+**For detailed reconciliation (per bank account):**
+
+```
+POST /api/v1/generate-reports/bank-reconciliation-details
+{ "primarySnapshotDate": "2025-12-31" }
+```
+
+### Step 10: Bank Balance Summary
+
+```
+POST /api/v1/generate-reports/bank-balance-summary
+{ "primarySnapshotDate": "2025-12-31" }
+```
+
+Summary of all bank account balances at year-end. Cross-reference to bank confirmation letters (which the auditor will request directly from your banks).
+
+---
+
+## Phase 5: Fixed Assets
+
+### Step 11: Fixed Assets Register
+
+```
+POST /api/v1/generate-reports/fixed-assets-summary
+```
+
+Shows all fixed assets: acquisition date, cost, depreciation method, useful life, accumulated depreciation, and net book value.
+
+**For FA reconciliation (movements during the year):**
+
+```
+POST /api/v1/generate-reports/fixed-assets-recon-summary
+```
+
+This shows: opening NBV + additions - disposals - depreciation = closing NBV. The auditor reconciles this to the trial balance.
+
+---
+
+## Phase 6: Tax
+
+### Step 12: Tax Ledger / GST Summary
+
+```
+POST /api/v1/generate-reports/vat-ledger
+{ "startDate": "2025-01-01", "endDate": "2025-12-31" }
+```
+
+Full year tax ledger for the auditor to verify GST returns filed during the year. The annual total should reconcile to the sum of the four quarterly GST F5 returns.
+
+---
+
+## Phase 7: Data Exports
+
+Auditors and tax agents often need the data in Excel format for their own workpapers.
+
+### Step 13: Export all key reports
+
+```
+POST /api/v1/data-exports/trial-balance
+{ "startDate": "2025-01-01", "endDate": "2025-12-31" }
+```
+
+```
+POST /api/v1/data-exports/profit-and-loss
+{ "startDate": "2025-01-01", "endDate": "2025-12-31" }
+```
+
+```
+POST /api/v1/data-exports/general-ledger
+{ "startDate": "2025-01-01", "endDate": "2025-12-31", "groupBy": "ACCOUNT" }
+```
+
+```
+POST /api/v1/data-exports/ar-report
+{ "endDate": "2025-12-31" }
+```
+
+```
+POST /api/v1/data-exports/ap-report
+{ "endDate": "2025-12-31" }
+```
+
+**Note:** Data export endpoints use simpler field names than generate-reports. P&L export uses `startDate`/`endDate` instead of `primarySnapshotDate`/`secondarySnapshotDate`.
+
+---
+
+## Phase 8: Supporting Schedules
+
+These are typically prepared manually by extracting data from the general ledger. The schedules explain what sits behind specific balance sheet line items.
+
+### Step 14: Compile supporting schedules
+
+**Prepaid Expenses Schedule:**
+- Search the general ledger for prepaid asset accounts
+- List each prepaid item: description, original amount, amortization to date, remaining balance
+- If using capsules for prepaid workflows, group the GL by capsule for a clean view
+
+**Loan Schedule:**
+- For each active loan: original principal, interest rate, monthly payment, balance at year-end
+- Extract from the loan capsule GL entries
+- **Calculator:** `jaz calc loan` produces the full amortization table
+
+**Provision Schedule:**
+- List all provisions: ECL/bad debt, employee leave, warranty, legal, etc.
+- For each: opening balance, additions, utilizations, reversals, closing balance
+- ECL provision: `jaz calc ecl` for the year-end calculation
+
+**Lease Schedule (if IFRS 16 applies):**
+- Right-of-use asset: opening, depreciation, closing
+- Lease liability: opening, interest, payments, closing
+- **Calculator:** `jaz calc lease` for the complete schedule
+
+**Fixed Deposit Schedule:**
+- List all fixed deposits: bank, principal, rate, maturity date, accrued interest
+- **Calculator:** `jaz calc fixed-deposit` for interest calculations
+
+**Intercompany Balances (if applicable):**
+- Receivables and payables with related parties
+- Must be disclosed separately in financial statements
+
+---
+
+## Phase 9: Final Checks
+
+### Step 15: Reconciliation checklist
+
+Before handing the pack to the auditor, verify these tie:
+
+| Account | Report | Should Match |
+|---------|--------|-------------|
+| Cash / Bank | Bank Recon Summary (Step 9) | Bank statements |
+| Accounts Receivable | AR Aging (Step 7) | Trial balance AR line |
+| Accounts Payable | AP Aging (Step 8) | Trial balance AP line |
+| Fixed Assets (NBV) | FA Register (Step 11) | Trial balance FA lines |
+| Revenue | P&L (Step 2) | GST return Box 1+2+3 totals |
+| GST Receivable/Payable | Tax Ledger (Step 12) | Sum of quarterly GST returns |
+
+### Step 16: Review for completeness
+
+Run through this checklist:
+
+- [ ] All bank accounts reconciled at year-end (zero unreconciled items or documented timing differences)
+- [ ] All supplier statements reconciled for major suppliers
+- [ ] Lock date set to year-end (prevents backdated entries during audit)
+- [ ] No draft transactions in the period (search for status = DRAFT and resolve)
+- [ ] Depreciation posted for all 12 months
+- [ ] Accruals and prepayments up to date
+- [ ] Intercompany balances agree with counterparty
+- [ ] Related party transactions identified and documented
+
+---
+
+## Audit Prep Checklist (Quick Reference)
+
+| # | Step | Phase | Report/Endpoint |
+|---|------|-------|----------------|
+| 1 | Trial Balance | Core | `POST /generate-reports/trial-balance` |
+| 2 | P&L | Core | `POST /generate-reports/profit-and-loss` |
+| 3 | Balance Sheet | Core | `POST /generate-reports/balance-sheet` |
+| 4 | General Ledger | Ledgers | `POST /generate-reports/general-ledger` |
+| 5 | Cashflow | Ledgers | `POST /generate-reports/cashflow` |
+| 6 | Equity Movement | Ledgers | `POST /generate-reports/equity-movement` |
+| 7 | AR Aging | Aging | `POST /generate-reports/ar-report` |
+| 8 | AP Aging | Aging | `POST /generate-reports/ap-report` |
+| 9 | Bank Recon Summary | Bank | `POST /generate-reports/bank-reconciliation-summary` |
+| 10 | Bank Balance Summary | Bank | `POST /generate-reports/bank-balance-summary` |
+| 11 | FA Register | Assets | `POST /generate-reports/fixed-assets-summary` |
+| 12 | Tax Ledger | Tax | `POST /generate-reports/vat-ledger` |
+| 13 | Data Exports | Export | `POST /data-exports/*` |
+| 14 | Supporting schedules | Schedules | Manual from GL + calculators |
+| 15 | Reconciliation checks | Final | Cross-reference all reports |
+| 16 | Completeness review | Final | Checklist |
+
+---
+
+## Tips for SMBs
+
+**Start early.** Don't wait for the auditor's request list. Generate the report pack in January for the prior year and have it ready before the engagement begins. A well-prepared client gets a faster, cheaper audit.
+
+**The auditor will ask for bank confirmation letters.** These are letters from your bank confirming balances at year-end. Request them from your bank in early January — they can take 2-4 weeks to arrive.
+
+**Keep a "passed adjustments" list.** If the auditor proposes adjustments you disagree with (within materiality), track them. Below-materiality items may accumulate — the auditor must consider cumulative effect.
+
+**IRAS filing deadlines (SG):**
+- Form C-S/C: November 30 of the following year (e.g., FY 2025 due Nov 30, 2026)
+- ECI (Estimated Chargeable Income): Within 3 months of financial year-end
+- GST F5: 1 month after each quarter-end
+
+**Common audit queries you can pre-empt:**
+- "Can you provide a schedule of revenue by customer?" → Run AR summary report
+- "What are the top 10 expenses?" → Run P&L, sort expense lines
+- "Are there any related party transactions?" → Tag them during the year, not at audit time
+- "Can you explain the $X increase in expenses?" → Have month-by-month P&L ready for variance analysis

package/assets/skills/jobs/references/bank-recon.md

@@ -0,0 +1,234 @@
+# Bank Reconciliation Catch-Up
+
+Clear unreconciled bank statement entries by matching them to existing transactions, creating missing ones, and flagging duplicates. This is the single most impactful thing you can do for book accuracy — a clean bank recon means cash is right, and cash being right means everything else has a fighting chance.
+
+**CLI:** `jaz jobs bank-recon [--account "DBS Current"] [--period 2025-01] [--json]`
+
+---
+
+## Phase 1: Identify Bank Accounts
+
+List all bank accounts in the org. If `--account` is specified, filter to that one. Otherwise, reconcile all of them.
+
+### Step 1: List bank accounts
+
+```
+GET /api/v1/bank-accounts?limit=100&offset=0
+```
+
+Or via CoA search (more reliable — gives you the resourceId directly):
+
+```
+POST /api/v1/chart-of-accounts/search
+{
+  "filter": { "accountType": { "eq": "Bank Accounts" } },
+  "sort": { "sortBy": ["name"], "order": "ASC" }
+}
+```
+
+**What you get:** A list of bank-type CoA accounts with `resourceId`, `name`, `currencyCode`. You need the `resourceId` for every subsequent step.
+
+---
+
+## Phase 2: Pull Unreconciled Items
+
+For each bank account, pull all unreconciled bank records. This is your working list.
+
+### Step 2: Search unreconciled bank records
+
+```
+POST /api/v1/bank-records/{accountResourceId}/search
+{
+  "filter": {
+    "status": { "eq": "UNRECONCILED" },
+    "valueDate": { "between": ["2025-01-01", "2025-01-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**Omit the `valueDate` filter** if you want to see ALL unreconciled items regardless of date. For a catch-up, you usually want everything.
+
+**What to check:**
+- Count of unreconciled items — this is your work queue
+- Any items older than 60 days are red flags (investigate immediately)
+- `netAmount` positive = cash-in, negative = cash-out
+- `extContactName` and `description` are your best clues for matching
+
+### Step 3: Check for possible duplicates
+
+```
+POST /api/v1/bank-records/{accountResourceId}/search
+{
+  "filter": { "status": { "eq": "POSSIBLE_DUPLICATE" } },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**Handle duplicates first.** If two bank feed entries have the same date, amount, and description, the system flags them as `POSSIBLE_DUPLICATE`. Review and archive the genuine duplicates before proceeding — otherwise you'll create double entries trying to reconcile them.
+
+---
+
+## Phase 3: Categorize and Resolve
+
+Work through each unreconciled item. There are four resolution paths.
+
+### Path A: Match to existing transaction
+
+The bank record matches an invoice payment, bill payment, or journal already in the books. This is the ideal case — the transaction exists, it just hasn't been linked to the bank record.
+
+**How to find the match:** Search cashflow transactions for the same amount and approximate date:
+
+```
+POST /api/v1/cashflow-transactions/search
+{
+  "filter": {
+    "organizationAccountResourceId": { "eq": "<bank-account-uuid>" },
+    "totalAmount": { "eq": 2500.00 },
+    "valueDate": { "between": ["2025-01-10", "2025-01-20"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "DESC" },
+  "limit": 20
+}
+```
+
+**Tip:** Widen the date range by a few days — bank processing delays mean the book date and bank date often differ by 1-3 business days.
+
+### Path B: Create missing transaction from attachment
+
+The bank record represents a real transaction, but nothing has been entered in the books yet. If you have the receipt, invoice, or bill document, use Jaz Magic to create the transaction automatically.
+
+```
+POST /api/v1/magic/createBusinessTransactionFromAttachment
+Content-Type: multipart/form-data
+
+Fields:
+  - sourceFile: <PDF or JPG of the invoice/receipt>
+  - businessTransactionType: "BILL" (for expenses) or "INVOICE" (for income)
+  - sourceType: "FILE"
+```
+
+Jaz Magic handles OCR, line item extraction, contact matching, and CoA mapping. It creates a draft transaction that you review and post.
+
+**When you don't have a document:** Create the transaction manually using the appropriate endpoint (invoice, bill, cash-in, cash-out).
+
+### Path C: Create cash journal for bank fees/charges
+
+Bank fees, interest charges, service charges, and similar items don't have a corresponding invoice or bill. Record them as cash-out journals.
+
+```
+POST /api/v1/cash-out-journals
+{
+  "saveAsDraft": false,
+  "reference": "BANK-FEE-JAN25-001",
+  "valueDate": "2025-01-15",
+  "accountResourceId": "<bank-account-uuid>",
+  "journalEntries": [
+    { "accountResourceId": "<bank-fees-expense-uuid>", "amount": 25.00, "type": "DEBIT", "name": "Monthly service charge — Jan 2025" }
+  ]
+}
+```
+
+For bank interest earned (cash-in):
+
+```
+POST /api/v1/cash-in-journals
+{
+  "saveAsDraft": false,
+  "reference": "BANK-INT-JAN25-001",
+  "valueDate": "2025-01-31",
+  "accountResourceId": "<bank-account-uuid>",
+  "journalEntries": [
+    { "accountResourceId": "<interest-income-uuid>", "amount": 12.50, "type": "CREDIT", "name": "Interest earned — Jan 2025" }
+  ]
+}
+```
+
+### Path D: Flag for investigation
+
+Some items don't have an obvious match or explanation. Flag these for the business owner or finance manager to investigate. Common causes:
+- Personal transactions through the business account
+- Refunds or chargebacks
+- Intercompany transfers not yet recorded
+- Errors in the bank feed (rare but happens)
+
+---
+
+## Phase 4: Verification
+
+After resolving all items, verify the reconciliation is clean.
+
+### Step 4: Re-check unreconciled count
+
+```
+POST /api/v1/bank-records/{accountResourceId}/search
+{
+  "filter": { "status": { "eq": "UNRECONCILED" } },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1
+}
+```
+
+**Target:** Zero unreconciled items for the period, or only genuine timing differences (outstanding cheques, deposits in transit that will clear next period).
+
+### Step 5: Bank balance summary
+
+```
+POST /api/v1/generate-reports/bank-balance-summary
+{ "primarySnapshotDate": "2025-01-31" }
+```
+
+**What to check:**
+- Book balance per Jaz should match the bank statement closing balance
+- Any difference should equal the sum of known timing items
+- Zero unreconciled difference = clean recon
+
+### Step 6: Bank reconciliation summary report
+
+```
+POST /api/v1/generate-reports/bank-reconciliation-summary
+{ "primarySnapshotDate": "2025-01-31" }
+```
+
+This gives you the formal reconciliation statement showing: opening balance + cash in - cash out = closing balance, with the reconciling items listed.
+
+---
+
+## Bank Recon Checklist (Quick Reference)
+
+| # | Step | Phase | What |
+|---|------|-------|------|
+| 1 | List bank accounts | Identify | Get all bank-type CoA accounts |
+| 2 | Pull unreconciled items | Pull | Search by status = UNRECONCILED |
+| 3 | Check duplicates | Pull | Review POSSIBLE_DUPLICATE items |
+| A | Match to existing | Resolve | Link to existing invoice/bill/journal |
+| B | Create from attachment | Resolve | Use Jaz Magic for documents |
+| C | Create cash journal | Resolve | Bank fees, interest, charges |
+| D | Flag for investigation | Resolve | Unexplained items |
+| 4 | Re-check count | Verify | Should be zero (or timing items only) |
+| 5 | Bank balance summary | Verify | Book balance = bank statement |
+| 6 | Reconciliation report | Verify | Formal reconciliation statement |
+
+---
+
+## Tips for SMBs
+
+**Do this weekly, not monthly.** A weekly 15-minute recon is far easier than a monthly 3-hour catch-up. Monday morning is ideal — reconcile the prior week's bank activity before the new week starts.
+
+**Set up bank rules for recurring items.** If you pay the same rent, subscription, or utility every month, create a bank rule to auto-categorize it. This eliminates the most repetitive part of recon.
+
+```
+POST /api/v1/bank-rules
+```
+
+**Use bank feeds if available.** Aspire and Airwallex direct feeds auto-import bank records daily. This eliminates the CSV import step entirely.
+
+**Don't let it pile up.** The longer a bank record sits unreconciled, the harder it is to figure out what it was. After 90 days, you're essentially doing forensic accounting. Stay current.
+
+**Common SMB bank fee accounts:**
+- Bank Charges / Bank Fees (operating expense)
+- Interest Expense (for overdraft/loan interest)
+- Interest Income (for savings/deposit interest)
+- Foreign Exchange Gain/Loss (for FX conversion fees)