jaz-cli 2.6.0 → 2.8.0

package/assets/skills/jobs/references/month-end-close.md

@@ -0,0 +1,308 @@
+# Month-End Close
+
+The monthly close is the foundation of accurate books. For an SMB, this typically takes 1-3 days depending on transaction volume and complexity. Every quarter-end and year-end builds on this.
+
+**CLI:** `jaz jobs month-end --period 2025-01 [--currency SGD] [--json]`
+
+---
+
+## Phase 1: Pre-Close Preparation
+
+Before adjusting anything, ensure the raw data is complete. These are verification steps — you're checking, not creating.
+
+### Step 1: Verify all sales invoices are entered
+
+Confirm every invoice issued during the period is in Jaz.
+
+```
+POST /invoices/search
+{
+  "filter": { "valueDate": { "between": ["2025-01-01", "2025-01-31"] } },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**What to check:** Compare the count and total against your sales records or POS system. Missing invoices = understated revenue.
+
+### Step 2: Verify all purchase bills are entered
+
+Confirm every bill received during the period is in Jaz. For SMBs, this is the most common gap — bills arrive late or sit in someone's inbox.
+
+```
+POST /bills/search
+{
+  "filter": { "valueDate": { "between": ["2025-01-01", "2025-01-31"] } },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**What to check:** Cross-reference against email, supplier portals, and physical mail. Late bills → missed expenses → overstated profit.
+
+**Tip:** If you have the bill document but haven't entered it yet, use **Jaz Magic** (`POST /magic/createBusinessTransactionFromAttachment`) — upload the PDF/JPG and let extraction & autofill handle it.
+
+### Step 3: Complete bank reconciliation
+
+This is the single most important pre-close step. Every bank account must be reconciled to its statement closing balance.
+
+```
+POST /bank-records/{accountResourceId}/search
+{
+  "filter": { "status": { "eq": "UNRECONCILED" } },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**What to check:**
+- All unreconciled items are genuine timing differences (outstanding cheques, deposits in transit)
+- No items older than 30 days (investigate and resolve)
+- Book balance per Jaz matches bank statement closing balance
+
+**See also:** `references/bank-recon.md` for the full bank reconciliation catch-up job.
+
+### Step 4: Review AR aging
+
+Identify overdue customer invoices. This feeds into credit control and bad debt assessment.
+
+```
+POST /generate-reports/ar-report
+{ "endDate": "2025-01-31" }
+```
+
+**What to check:**
+- Total AR ties to Accounts Receivable on trial balance
+- Flag invoices overdue > 30/60/90 days
+- Consider bad debt provision if material (→ Phase 3)
+
+### Step 5: Review AP aging
+
+Identify upcoming and overdue supplier payments. This feeds into payment planning.
+
+```
+POST /generate-reports/ap-report
+{ "endDate": "2025-01-31" }
+```
+
+**What to check:**
+- Total AP ties to Accounts Payable on trial balance
+- Identify bills due in the next 7-14 days for the payment run
+- Flag any disputed or held bills
+
+---
+
+## Phase 2: Accruals & Adjustments
+
+Record transactions that belong to this period but aren't yet in the books. This is where recipes come in.
+
+### Step 6: Record accrued expenses
+
+Expenses incurred but not yet billed (utilities, professional services, cleaning, etc.). The most common month-end adjustment for SMBs.
+
+**Recipe:** `accrued-expenses`
+**Pattern:** DR Expense, CR Accrued Liabilities → reverse on Day 1 of next month
+
+```
+POST /journals
+{
+  "valueDate": "2025-01-31",
+  "reference": "ME-ACCR-JAN25",
+  "journalEntries": [
+    { "accountResourceId": "<expense-account>", "amount": 500.00, "type": "DEBIT", "name": "Electricity accrual — Jan 2025" },
+    { "accountResourceId": "<accrued-liabilities>", "amount": 500.00, "type": "CREDIT", "name": "Electricity accrual — Jan 2025" }
+  ]
+}
+```
+
+**Conditional:** Only if there are expenses not yet billed for the period. Common examples: utilities, internet, cleaning, accounting fees.
+
+### Step 7: Amortize prepaid expenses
+
+If you've set up prepaid expense capsules with schedulers, verify the scheduler fired for this month. If not, post the amortization journal manually.
+
+**Recipe:** `prepaid-amortization` | **Calculator:** `jaz calc prepaid-expense`
+**Pattern:** DR Expense, CR Prepaid Asset
+
+**Verification:** Search for journals in the prepaid capsule for this period:
+```
+POST /journals/search
+{
+  "filter": {
+    "valueDate": { "between": ["2025-01-01", "2025-01-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "DESC" },
+  "limit": 100
+}
+```
+
+Filter results by capsule name (e.g., "FY2025 Office Insurance") to confirm the entry exists.
+
+### Step 8: Recognize deferred revenue
+
+If you've received upfront payments that should be recognized over time, verify the scheduler fired or post manually.
+
+**Recipe:** `deferred-revenue` | **Calculator:** `jaz calc deferred-revenue`
+**Pattern:** DR Deferred Revenue (liability), CR Revenue
+
+**Conditional:** Only if your business has subscription or prepaid revenue models.
+
+### Step 9: Record depreciation
+
+For fixed assets, record the monthly depreciation charge. Jaz supports straight-line natively via fixed assets. For declining balance or 150DB methods, use the calculator and post manual journals.
+
+**Recipe:** `declining-balance` | **Calculator:** `jaz calc depreciation`
+**Pattern:** DR Depreciation Expense, CR Accumulated Depreciation
+
+**If using native Jaz FA depreciation:** Verify auto-calculated depreciation is running correctly via the FA register.
+**If using non-standard methods:** Post manual journal from calculator output.
+
+### Step 10: Accrue employee benefits
+
+Record monthly leave accrual. If using a scheduler, verify it fired.
+
+**Recipe:** `employee-accruals`
+**Pattern:** DR Leave Expense, CR Leave Liability (monthly fixed amount from scheduler)
+
+**Conditional:** Only if you track leave balances. Most SMBs with 5+ employees should.
+
+### Step 11: Accrue loan interest
+
+If you have bank loans, verify the interest portion of this month's payment is correctly recorded. If payments are embedded in bill/cash-out entries, this may already be handled.
+
+**Recipe:** `bank-loan` | **Calculator:** `jaz calc loan`
+**Pattern:** Interest splits from principal in each payment — verify the amortization table matches.
+
+**Conditional:** Only if you have active loans. Skip if loan payments are already correctly coded.
+
+---
+
+## Phase 3: Period-End Valuations
+
+Adjustments that depend on period-end rates or balances. These are less common for simple SMBs but critical for accuracy.
+
+### Step 12: FX revaluation
+
+If your org has foreign currency monetary items (bank accounts, receivables, payables in non-base currency), revalue them at period-end exchange rates.
+
+**Recipe:** `fx-revaluation` | **Calculator:** `jaz calc fx-reval`
+**Pattern:** DR/CR FX Unrealized Gain/Loss for the difference between book rate and closing rate. Post a Day 1 reversal.
+
+```bash
+jaz calc fx-reval --amount 50000 --book-rate 1.35 --closing-rate 1.38 --currency USD --base-currency SGD
+```
+
+**Conditional:** Only if multi-currency org with material foreign currency balances. Many SGD-only SMBs can skip this.
+
+**Note:** Jaz auto-handles FX on AR/AP (invoices/bills in foreign currency). This step is for non-AR/AP items only (foreign currency bank accounts, deposits, intercompany balances).
+
+### Step 13: Review bad debt provision (ECL)
+
+Assess whether the bad debt provision needs adjusting based on the AR aging report from Step 4.
+
+**Recipe:** `bad-debt-provision` | **Calculator:** `jaz calc ecl`
+**Pattern:** DR Bad Debt Expense, CR Allowance for Doubtful Debts
+
+```bash
+jaz calc ecl --current 100000 --30d 50000 --60d 20000 --90d 10000 --120d 5000 --rates 0.5,2,5,10,50
+```
+
+**Conditional:** Review monthly, but typically adjust quarterly unless there's a significant change (e.g., major customer default). For most SMBs, a quick mental check is sufficient monthly — formal ECL review in quarter-end.
+
+---
+
+## Phase 4: Verification
+
+Run the numbers. Everything should tie.
+
+### Step 14: Review trial balance
+
+The master check. Total debits must equal total credits.
+
+```
+POST /generate-reports/trial-balance
+{ "startDate": "2025-01-01", "endDate": "2025-01-31" }
+```
+
+**What to check:**
+- Debits = Credits (always — if not, something is seriously wrong)
+- Cash/bank accounts match bank statements
+- AR balance matches AR aging total from Step 4
+- AP balance matches AP aging total from Step 5
+- No unexpected balances (negative cash, credit balances in expense accounts)
+
+### Step 15: Generate P&L
+
+```
+POST /generate-reports/profit-and-loss
+{ "primarySnapshotDate": "2025-01-31", "secondarySnapshotDate": "2025-01-01" }
+```
+
+**What to check:**
+- Revenue is in line with expectations
+- Expenses make sense for the month
+- Gross margin is reasonable
+- Any large one-off items should be explainable (accruals, adjustments from Phase 2)
+
+### Step 16: Generate balance sheet
+
+```
+POST /generate-reports/balance-sheet
+{ "primarySnapshotDate": "2025-01-31" }
+```
+
+**What to check:**
+- Assets = Liabilities + Equity (by definition — if not, the API has a bug)
+- Cash position is reasonable
+- Prepaid balances reduced by one month's amortization
+- Accrued liabilities reflect the accruals from Phase 2
+
+### Step 17: Compare to prior month
+
+Run the same P&L for the prior month and compare. Significant variances should be explainable.
+
+```
+POST /generate-reports/profit-and-loss
+{ "primarySnapshotDate": "2024-12-31", "secondarySnapshotDate": "2024-12-01" }
+```
+
+**Flag:** Revenue or expense lines that moved > 20% month-over-month without a clear reason.
+
+---
+
+## Phase 5: Close & Lock
+
+Once everything checks out, lock the period to prevent accidental backdated entries.
+
+### Step 18: Set lock date
+
+Move the org lock date forward to the last day of the closed month.
+
+**Best practice:** Lock date = last day of the closed period (e.g., `2025-01-31` after January close).
+
+**Important:** Only move the lock date forward. Moving it backward reopens prior periods — do this only if you need to post corrections (and re-close afterward).
+
+---
+
+## Month-End Close Checklist (Quick Reference)
+
+| # | Step | Phase | Conditional | Recipe/Calc |
+|---|------|-------|-------------|-------------|
+| 1 | Verify invoices entered | Pre-close | Always | — |
+| 2 | Verify bills entered | Pre-close | Always | — |
+| 3 | Complete bank reconciliation | Pre-close | Always | bank-recon job |
+| 4 | Review AR aging | Pre-close | Always | — |
+| 5 | Review AP aging | Pre-close | Always | — |
+| 6 | Record accrued expenses | Accruals | If unbilled expenses exist | accrued-expenses |
+| 7 | Amortize prepaid expenses | Accruals | If prepaid capsules exist | prepaid-amortization / `jaz calc prepaid-expense` |
+| 8 | Recognize deferred revenue | Accruals | If deferred revenue exists | deferred-revenue / `jaz calc deferred-revenue` |
+| 9 | Record depreciation | Accruals | If fixed assets exist | declining-balance / `jaz calc depreciation` |
+| 10 | Accrue employee benefits | Accruals | If tracking leave | employee-accruals |
+| 11 | Accrue loan interest | Accruals | If active loans | bank-loan / `jaz calc loan` |
+| 12 | FX revaluation | Valuations | If multi-currency | fx-revaluation / `jaz calc fx-reval` |
+| 13 | Review bad debt provision | Valuations | If material AR change | bad-debt-provision / `jaz calc ecl` |
+| 14 | Review trial balance | Verification | Always | — |
+| 15 | Generate P&L | Verification | Always | — |
+| 16 | Generate balance sheet | Verification | Always | — |
+| 17 | Compare to prior month | Verification | Always | — |
+| 18 | Set lock date | Close | Always | — |

package/assets/skills/jobs/references/payment-run.md

@@ -0,0 +1,246 @@
+# Payment Run (Bulk Bill Payments)
+
+Process outstanding supplier bills in a structured batch. A payment run typically happens weekly or fortnightly — you identify what's due, group by supplier, approve the batch, and record the payments. This keeps supplier relationships healthy and avoids late payment penalties.
+
+**CLI:** `jaz jobs payment-run [--due-before 2025-02-28] [--json]`
+
+---
+
+## Phase 1: Identify Outstanding Bills
+
+### Step 1: List all unpaid bills
+
+Pull every posted bill with an outstanding balance:
+
+```
+POST /api/v1/bills/search
+{
+  "filter": {
+    "status": { "eq": "POSTED" },
+    "balanceAmount": { "gt": 0 }
+  },
+  "sort": { "sortBy": ["dueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**What you get:** All unpaid bills sorted by due date (earliest first). Each result includes `balanceAmount` (remaining unpaid), `totalAmount` (original), `dueDate`, and contact details.
+
+### Step 2: Filter by due date
+
+If `--due-before` is specified, narrow to bills due on or before that date:
+
+```
+POST /api/v1/bills/search
+{
+  "filter": {
+    "status": { "eq": "POSTED" },
+    "balanceAmount": { "gt": 0 },
+    "dueDate": { "lte": "2025-02-28" }
+  },
+  "sort": { "sortBy": ["dueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**Tip:** Include bills due in the next 7 days beyond your cutoff — paying a few days early is better than missing one because it was due the day after your run.
+
+---
+
+## Phase 2: Group and Summarize
+
+### Step 3: Group by supplier
+
+Organize the bills by `contactResourceId`. For each supplier, summarize:
+
+- Number of bills
+- Total amount due
+- Earliest due date
+- Currency (important for FX payments)
+
+**Why group:** Suppliers prefer a single consolidated payment over multiple small ones. It also reduces bank transaction fees for the payer.
+
+### Step 4: Generate AP aging for context
+
+```
+POST /api/v1/generate-reports/ap-report
+{ "endDate": "2025-02-28" }
+```
+
+**What to check:**
+- Total AP aging should match the sum of all unpaid bills from Step 1
+- Identify any bills in the 60d+ aging buckets — these are overdue and may need priority payment or dispute resolution
+- Flag disputed bills (do NOT include them in the payment run)
+
+---
+
+## Phase 3: Select and Approve
+
+### Step 5: Build the payment batch
+
+Select which bills to pay. Three common approaches:
+
+**All-due:** Pay everything due on or before the cutoff date. Simplest, works for most SMBs.
+
+**Priority-based:** Pay overdue first (60d+, then 30d+), then current. Useful when cash is tight.
+
+**Supplier-based:** Pay strategic suppliers first (sole suppliers, key relationships), then others. Business judgment call.
+
+**Before proceeding:** Confirm cash availability. Check the bank balance:
+
+```
+POST /api/v1/generate-reports/bank-balance-summary
+{ "primarySnapshotDate": "2025-02-28" }
+```
+
+If total payments exceed available cash, prioritize and defer the rest to the next run.
+
+---
+
+## Phase 4: Record Payments
+
+### Step 6: Record payment for each bill
+
+For each bill in the approved batch, record the payment:
+
+```
+POST /api/v1/bills/{billResourceId}/payments
+{
+  "payments": [{
+    "paymentAmount": 5350.00,
+    "transactionAmount": 5350.00,
+    "accountResourceId": "<bank-account-uuid>",
+    "paymentMethod": "BANK_TRANSFER",
+    "reference": "PAYRUN-2025-02-28-001",
+    "valueDate": "2025-02-28"
+  }]
+}
+```
+
+**CRITICAL field notes:**
+- `paymentAmount` — The amount leaving the bank account (bank currency)
+- `transactionAmount` — The amount applied to the bill balance (bill currency). Same as `paymentAmount` for same-currency. Different for FX (see below).
+- `accountResourceId` — The bank account UUID (NOT the expense account)
+- `paymentMethod` — Use `"BANK_TRANSFER"` for electronic payments. Other options: `"CHEQUE"`, `"CASH"`, `"CREDIT_CARD"`, `"E_WALLET"`
+- `reference` — Use a consistent naming convention (e.g., `PAYRUN-{date}-{seq}`)
+- `valueDate` — The date the payment is made (YYYY-MM-DD format)
+
+Always wrap in `{ "payments": [...] }` even for a single payment.
+
+**Note:** There is no batch payment endpoint yet. Each bill requires an individual `POST /bills/{id}/payments` call. If you're paying 50 bills, that's 50 API calls. The batch endpoint is planned but not yet available.
+
+### Step 7: Partial payments
+
+If paying less than the full balance (e.g., cash constraints or instalment arrangement), set `paymentAmount` and `transactionAmount` to the partial amount. The bill remains in `POSTED` status with a reduced `balanceAmount`.
+
+```
+POST /api/v1/bills/{billResourceId}/payments
+{
+  "payments": [{
+    "paymentAmount": 2000.00,
+    "transactionAmount": 2000.00,
+    "accountResourceId": "<bank-account-uuid>",
+    "paymentMethod": "BANK_TRANSFER",
+    "reference": "PAYRUN-2025-02-28-PARTIAL",
+    "valueDate": "2025-02-28"
+  }]
+}
+```
+
+---
+
+## Phase 5: FX Payments
+
+**Conditional:** Only if paying bills in a non-base currency.
+
+### Step 8: Record FX payment
+
+When paying a foreign currency bill from a base currency bank account (e.g., paying a USD bill from an SGD account):
+
+```
+POST /api/v1/bills/{billResourceId}/payments
+{
+  "payments": [{
+    "paymentAmount": 6750.00,
+    "transactionAmount": 5000.00,
+    "accountResourceId": "<sgd-bank-account-uuid>",
+    "paymentMethod": "BANK_TRANSFER",
+    "reference": "PAYRUN-2025-02-28-FX",
+    "valueDate": "2025-02-28"
+  }]
+}
+```
+
+Here `paymentAmount` is 6,750 SGD (what left the bank) and `transactionAmount` is 5,000 USD (what was applied to the bill). The platform calculates the implied exchange rate and posts any FX gain/loss automatically.
+
+**Tip:** Check the actual bank debit amount against your bank statement. Banks often add a spread to the exchange rate — the SGD amount debited may differ from what you'd calculate using the mid-market rate.
+
+---
+
+## Phase 6: Verification
+
+### Step 9: Verify AP aging reflects the payments
+
+```
+POST /api/v1/generate-reports/ap-report
+{ "endDate": "2025-02-28" }
+```
+
+**What to check:**
+- Total AP should be reduced by the sum of all payments made
+- Bills that were fully paid should no longer appear in the aging
+- Partially paid bills should show the correct reduced balance
+
+### Step 10: Verify bank balance
+
+```
+POST /api/v1/generate-reports/bank-balance-summary
+{ "primarySnapshotDate": "2025-02-28" }
+```
+
+**What to check:**
+- Bank balance should be reduced by the total payment amount
+- Cross-reference to the actual bank statement to confirm all payments cleared
+
+---
+
+## Payment Run Checklist (Quick Reference)
+
+| # | Step | Phase | Conditional |
+|---|------|-------|-------------|
+| 1 | List unpaid bills | Identify | Always |
+| 2 | Filter by due date | Identify | If --due-before specified |
+| 3 | Group by supplier | Summarize | Always |
+| 4 | Generate AP aging | Summarize | Always |
+| 5 | Build payment batch | Select | Always |
+| 6 | Record each payment | Pay | Always |
+| 7 | Partial payments | Pay | If cash constraints |
+| 8 | FX payments | Pay | If multi-currency bills |
+| 9 | Verify AP aging | Verify | Always |
+| 10 | Verify bank balance | Verify | Always |
+
+---
+
+## Payment Method Options
+
+| Method | When to Use | Code |
+|--------|-------------|------|
+| Bank transfer | Most common for SMBs — GIRO, FAST, wire | `BANK_TRANSFER` |
+| Cheque | Decreasing usage but some suppliers still require it | `CHEQUE` |
+| Cash | Petty cash payments, small amounts | `CASH` |
+| Credit card | Corporate card payments | `CREDIT_CARD` |
+| E-wallet | GrabPay, PayNow for business | `E_WALLET` |
+
+---
+
+## Tips for SMBs
+
+**Run payments on a schedule.** Weekly (Friday) or fortnightly. Predictable payment cycles help with cash flow planning and reduce the "can you pay this urgently" interruptions.
+
+**Use payment terms strategically.** If a supplier offers 2% 10 Net 30 (2% discount for paying within 10 days), that's equivalent to a 36% annualized return. Take early payment discounts when cash allows.
+
+**Keep a buffer.** Don't pay everything that's due if it drains the account. Always maintain a cash buffer of at least 2 weeks of operating expenses.
+
+**Payment reference convention:** Use a consistent format like `PAYRUN-YYYY-MM-DD-SEQ` so payments are easy to trace in both your books and the bank statement. This makes bank reconciliation much easier downstream.
+
+**Approval workflow:** For SMBs with multiple signatories, build the payment list first, get approval, then execute. Don't record payments in Jaz until the actual bank transfer is initiated.