jaz-cli 2.7.0 → 2.8.0

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.

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

@@ -0,0 +1,268 @@
+# Quarter-End Close
+
+The quarterly close builds on the monthly close. It is month-end close repeated three times, plus a set of quarterly-specific adjustments that only make sense at three-month intervals. For most SMBs, this adds half a day to a day of extra work on top of the regular month-end.
+
+**CLI:** `jaz jobs quarter-end --period 2025-Q1 [--currency SGD] [--json]`
+
+**Standalone vs Incremental:**
+- **Standalone (default):** Generates the full plan — all monthly close steps for each of the three months in the quarter, followed by the quarterly extras. Use this when months haven't been closed yet.
+- **Incremental (`--incremental`):** Generates only the quarterly extras below. Use this when all three months are already closed and locked.
+
+---
+
+## Phase 1–5: Monthly Close (x3)
+
+Complete the full month-end close for each month in the quarter. Each month follows the same 5-phase, 18-step process.
+
+**Reference:** `references/month-end-close.md`
+
+| Quarter | Month 1 | Month 2 | Month 3 |
+|---------|---------|---------|---------|
+| Q1 (Jan–Mar) | January close | February close | March close |
+| Q2 (Apr–Jun) | April close | May close | June close |
+| Q3 (Jul–Sep) | July close | August close | September close |
+| Q4 (Oct–Dec) | October close | November close | December close |
+
+**Important:** Close months in order. Month 1 must be locked before starting Month 2, and Month 2 before Month 3. The quarterly extras run after Month 3 is closed.
+
+---
+
+## Phase 6: Quarterly Extras
+
+These steps run once per quarter, after all three months are closed. They address items that are reviewed less frequently or that accumulate over the quarter.
+
+### Step Q1: GST/VAT filing preparation
+
+Generate the tax ledger for the full quarter and reconcile input/output tax for filing.
+
+```
+POST /generate-reports/vat-ledger
+{ "startDate": "2025-01-01", "endDate": "2025-03-31" }
+```
+
+**What to do:**
+1. Pull the quarterly tax ledger report
+2. Review output tax (GST on sales) — verify every taxable invoice is included and the correct tax code was applied
+3. Review input tax (GST on purchases) — verify every claimable bill is included, no blocked input tax claimed
+4. Identify discrepancies — missing invoices/bills, wrong tax codes, exempt items coded as taxable
+5. Cross-reference totals to the GST return form
+
+**For Singapore (IRAS):**
+- Quarterly filing (standard GST-registered businesses)
+- File via myTax Portal within one month after quarter end
+- Box 1 (Total Sales): total revenue incl. zero-rated and exempt
+- Box 6 (Output Tax): from tax ledger output tax total
+- Box 7 (Input Tax): from tax ledger input tax total (net of blocked items)
+
+**For Philippines (BIR):**
+- Monthly VAT return (BIR Form 2550M) for each month in the quarter
+- Quarterly VAT return (BIR Form 2550Q) for the full quarter
+- Input VAT carried forward if excess over output VAT
+- File within 25 days after the close of the taxable quarter
+
+**Verification:** Output tax per tax ledger should equal sum of GST on all sales invoices for the quarter. Input tax per tax ledger should equal sum of GST on all purchase bills (excluding blocked items). Any difference = data entry error to investigate.
+
+**See also:** `references/gst-vat-filing.md` for the full GST/VAT filing job.
+
+### Step Q2: ECL / bad debt provision — formal review
+
+The monthly close includes a quick bad debt check (Step 13). The quarterly review is the formal one — full aged receivables analysis with loss rates applied.
+
+**Recipe:** `bad-debt-provision` | **Calculator:** `jaz calc ecl`
+
+**Step-by-step:**
+
+1. Pull the AR aging report as at quarter-end:
+```
+POST /generate-reports/ar-report
+{ "endDate": "2025-03-31" }
+```
+
+2. Categorize receivables into aging buckets (current, 30d, 60d, 90d, 120d+)
+
+3. Apply historical loss rates to each bucket:
+```bash
+jaz calc ecl --current 100000 --30d 50000 --60d 20000 --90d 10000 --120d 5000 --rates 0.5,2,5,10,50
+```
+
+4. Compare the calculated provision to the existing Allowance for Doubtful Debts balance on the trial balance
+
+5. Post an adjustment journal for the difference:
+```
+POST /journals
+{
+  "valueDate": "2025-03-31",
+  "reference": "QE-ECL-Q1-25",
+  "journalEntries": [
+    { "accountResourceId": "<bad-debt-expense>", "amount": 1250.00, "type": "DEBIT", "name": "ECL provision adjustment — Q1 2025" },
+    { "accountResourceId": "<allowance-doubtful-debts>", "amount": 1250.00, "type": "CREDIT", "name": "ECL provision adjustment — Q1 2025" }
+  ]
+}
+```
+
+**Note:** If the required provision has decreased, reverse the direction (DR Allowance, CR Bad Debt Expense). Some firms use a separate recovery account for write-backs.
+
+**Conditional:** Always perform the formal review at quarter-end, even if the monthly quick checks showed no change. Document the analysis — auditors will ask for it.
+
+### Step Q3: Bonus accrual true-up
+
+Review quarterly bonus obligations and adjust the accrual if estimates have changed.
+
+**Recipe:** `employee-accruals` (bonus component)
+
+During monthly closes, you accrue a fixed monthly estimate (1/12 of expected annual bonus). At quarter-end, re-assess whether the estimate is still accurate based on actual performance.
+
+**Step-by-step:**
+
+1. Verify three months of bonus accruals exist. Search for journals in the Employee Benefits capsule:
+```
+POST /journals/search
+{
+  "filter": {
+    "valueDate": { "between": ["2025-01-01", "2025-03-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 100
+}
+```
+Filter results by capsule or reference prefix (e.g., "BONUS-ACCR") to isolate bonus entries.
+
+2. Sum the year-to-date accrual and compare to the revised full-year estimate
+
+3. If the estimate has changed, post a true-up journal:
+```
+POST /journals
+{
+  "valueDate": "2025-03-31",
+  "reference": "QE-BONUS-Q1-25",
+  "journalEntries": [
+    { "accountResourceId": "<bonus-expense>", "amount": 2000.00, "type": "DEBIT", "name": "Bonus accrual true-up — Q1 2025" },
+    { "accountResourceId": "<bonus-liability>", "amount": 2000.00, "type": "CREDIT", "name": "Bonus accrual true-up — Q1 2025" }
+  ]
+}
+```
+
+**Conditional:** Only if the business has bonus schemes. Most SMBs with 5+ employees and a performance bonus structure should review quarterly. If no change to estimate, document the review but skip the journal.
+
+### Step Q4: Intercompany reconciliation
+
+If the business operates multiple entities (e.g., SG parent + PH subsidiary), reconcile intercompany balances and post settlement journals.
+
+**Recipe:** `intercompany`
+
+**Step-by-step:**
+
+1. Pull the trial balance for each entity and isolate intercompany receivable/payable accounts:
+```
+POST /generate-reports/trial-balance
+{ "startDate": "2025-01-01", "endDate": "2025-03-31" }
+```
+
+2. Verify that Entity A's intercompany receivable = Entity B's intercompany payable (and vice versa). Differences indicate:
+   - Transactions recorded in one entity but not the other
+   - Timing differences (one entity booked end-of-quarter, the other booked beginning of next)
+   - FX differences if the entities operate in different currencies
+
+3. Post matching journals in both entities to clear discrepancies
+
+4. If settling (netting off balances), post settlement journals:
+```
+POST /journals
+{
+  "valueDate": "2025-03-31",
+  "reference": "QE-IC-SETTLE-Q1-25",
+  "journalEntries": [
+    { "accountResourceId": "<intercompany-payable>", "amount": 15000.00, "type": "DEBIT", "name": "IC settlement — Entity A, Q1 2025" },
+    { "accountResourceId": "<bank-account>", "amount": 15000.00, "type": "CREDIT", "name": "IC settlement — Entity A, Q1 2025" }
+  ]
+}
+```
+
+**Conditional:** Only if multi-entity. Single-entity SMBs skip this entirely.
+
+### Step Q5: Provision unwinding
+
+If IAS 37 provisions exist (e.g., restoration obligations, warranty provisions, legal claims), post the quarterly discount unwinding journal.
+
+**Recipe:** `provisions` | **Calculator:** `jaz calc provision`
+
+Provisions measured at present value must have the discount unwound each period, recognizing the time value of money as a finance cost.
+
+```bash
+jaz calc provision --amount 500000 --rate 4 --term 60 --start-date 2025-01-01 --json
+```
+
+The calculator generates the unwinding schedule. Post the quarterly entry:
+
+```
+POST /journals
+{
+  "valueDate": "2025-03-31",
+  "reference": "QE-PROV-UNWIND-Q1-25",
+  "journalEntries": [
+    { "accountResourceId": "<finance-cost>", "amount": 4975.00, "type": "DEBIT", "name": "Provision discount unwinding — Q1 2025" },
+    { "accountResourceId": "<provision-liability>", "amount": 4975.00, "type": "CREDIT", "name": "Provision discount unwinding — Q1 2025" }
+  ]
+}
+```
+
+**Conditional:** Only if IAS 37 provisions exist with a discounting component. Most simple SMBs won't have these. Common in businesses with lease restoration obligations or long-term warranty commitments.
+
+---
+
+## Phase 7: Quarterly Verification
+
+Run the standard period verification (see `references/building-blocks.md` — Period Verification Pattern) for the full quarter, plus these quarterly-specific checks.
+
+### Standard verification (full quarter)
+
+```
+POST /generate-reports/trial-balance
+{ "startDate": "2025-01-01", "endDate": "2025-03-31" }
+```
+
+```
+POST /generate-reports/profit-and-loss
+{ "primarySnapshotDate": "2025-03-31", "secondarySnapshotDate": "2025-01-01" }
+```
+
+```
+POST /generate-reports/balance-sheet
+{ "primarySnapshotDate": "2025-03-31" }
+```
+
+### Quarterly-specific checks
+
+**GST reconciliation:**
+- Tax ledger output tax total = sum of GST on all sales invoices for Q1
+- Tax ledger input tax total = sum of GST on all purchase bills (less blocked items) for Q1
+- Net GST payable/refundable per tax ledger matches the amount on the GST return form
+- If you already filed monthly VAT returns (PH), quarterly total should equal sum of the three monthly returns
+
+**ECL provision balance:**
+- Allowance for Doubtful Debts on the balance sheet matches the calculated ECL from Step Q2
+- Bad Debt Expense on the P&L is reasonable relative to revenue
+
+**Intercompany balance check (if multi-entity):**
+- Entity A's intercompany receivable = Entity B's intercompany payable
+- Net intercompany position across all entities = zero (eliminates on consolidation)
+
+**Bonus accrual reasonableness:**
+- Bonus Liability on the balance sheet = (monthly accrual x months elapsed) + any true-ups
+- Bonus Expense on the P&L is proportional to the period (e.g., Q1 = ~25% of full-year estimate)
+
+---
+
+## Quarter-End Close Checklist (Quick Reference)
+
+| # | Step | Phase | Conditional | Recipe/Calc |
+|---|------|-------|-------------|-------------|
+| 1–18 | Month 1 close (all steps) | Monthly | Always | See month-end-close.md |
+| 1–18 | Month 2 close (all steps) | Monthly | Always | See month-end-close.md |
+| 1–18 | Month 3 close (all steps) | Monthly | Always | See month-end-close.md |
+| Q1 | GST/VAT filing preparation | Quarterly | Always (if GST-registered) | gst-vat-filing job |
+| Q2 | ECL / bad debt provision review | Quarterly | Always | bad-debt-provision / `jaz calc ecl` |
+| Q3 | Bonus accrual true-up | Quarterly | If bonus schemes exist | employee-accruals |
+| Q4 | Intercompany reconciliation | Quarterly | If multi-entity | intercompany |
+| Q5 | Provision unwinding | Quarterly | If IAS 37 provisions exist | provisions / `jaz calc provision` |
+| V | Quarterly verification | Verification | Always | — |