jaz-cli 2.6.0 → 2.8.0

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 | — |

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

@@ -0,0 +1,330 @@
+# Supplier Statement Reconciliation
+
+Compare your accounts payable balance for a supplier against the supplier's own statement. Identify missing bills, duplicate payments, pricing discrepancies, and timing differences. This is how you catch errors before they become disputes.
+
+**CLI:** `jaz jobs supplier-recon [--supplier "Acme Corp"] [--period 2025-01] [--json]`
+
+---
+
+## Phase 1: Get Supplier Details
+
+### Step 1: Find the supplier contact
+
+If `--supplier` is specified, search by name:
+
+```
+POST /api/v1/contacts/search
+{
+  "filter": {
+    "supplier": { "eq": true },
+    "name": { "contains": "Acme Corp" }
+  },
+  "sort": { "sortBy": ["name"], "order": "ASC" },
+  "limit": 10
+}
+```
+
+If no supplier is specified, list all suppliers:
+
+```
+POST /api/v1/contacts/search
+{
+  "filter": { "supplier": { "eq": true } },
+  "sort": { "sortBy": ["name"], "order": "ASC" },
+  "limit": 100
+}
+```
+
+**What you need:** The supplier's `resourceId` and `name` for all subsequent queries.
+
+---
+
+## Phase 2: Pull Your Records
+
+### Step 2: List all bills for the supplier in the period
+
+```
+POST /api/v1/bills/search
+{
+  "filter": {
+    "contactResourceId": { "eq": "<supplier-uuid>" },
+    "status": { "in": ["POSTED", "VOIDED"] },
+    "valueDate": { "between": ["2025-01-01", "2025-01-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**Include VOIDED status** — you need to see voided bills to explain differences (e.g., "we voided your invoice #123 because it was a duplicate").
+
+**Record for each bill:**
+- Reference number
+- Date
+- Total amount
+- Balance amount (how much is still unpaid)
+- Status
+
+### Step 3: List all payments to the supplier in the period
+
+Search for payment transactions against the supplier's bills. First, get all bills (from Step 2), then check each bill's payment records:
+
+```
+GET /api/v1/bills/{billResourceId}/payments
+```
+
+Alternatively, search cashflow transactions for supplier payments:
+
+```
+POST /api/v1/cashflow-transactions/search
+{
+  "filter": {
+    "contact": { "name": { "eq": "Acme Corp" } },
+    "businessTransactionType": { "in": ["PURCHASE"] },
+    "direction": { "eq": "PAYOUT" },
+    "valueDate": { "between": ["2025-01-01", "2025-01-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+### Step 4: List any supplier credit notes
+
+```
+POST /api/v1/supplier-credit-notes/search
+{
+  "filter": {
+    "contactResourceId": { "eq": "<supplier-uuid>" },
+    "status": { "eq": "POSTED" },
+    "valueDate": { "between": ["2025-01-01", "2025-01-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 100
+}
+```
+
+---
+
+## Phase 3: Get the Supplier Statement Balance
+
+### Step 5: Determine the AP balance per your books
+
+Get the AP balance for this specific supplier from the AP aging report:
+
+```
+POST /api/v1/generate-reports/ap-report
+{ "endDate": "2025-01-31" }
+```
+
+Look for the supplier in the report output and note their total balance.
+
+Alternatively, for a quick per-supplier calculation:
+
+```
+POST /api/v1/bills/search
+{
+  "filter": {
+    "contactResourceId": { "eq": "<supplier-uuid>" },
+    "status": { "eq": "POSTED" },
+    "balanceAmount": { "gt": 0 }
+  },
+  "sort": { "sortBy": ["dueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+Sum the `balanceAmount` from all results = your AP balance for this supplier.
+
+### Step 6: Compare to supplier's statement
+
+The supplier's statement is an external document — you'll have it as a PDF, email, or portal download. The key figure is their **closing balance** for the period.
+
+**The reconciliation equation:**
+
+```
+Your AP balance (from Step 5)
+  SHOULD EQUAL
+Supplier's statement closing balance
+
+If they don't match, the difference is explained by reconciling items (Phase 4).
+```
+
+---
+
+## Phase 4: Identify Differences
+
+Work through each discrepancy type systematically.
+
+### Difference Type 1: Missing bills (in supplier statement, not in your books)
+
+The supplier has invoiced you, but the bill isn't entered in Jaz.
+
+**Common causes:**
+- Bill arrived late (still in someone's inbox or physical mailbox)
+- Bill was emailed to the wrong person
+- Bill was received but not yet entered by the bookkeeper
+
+**Resolution:** Obtain the bill from the supplier and enter it:
+
+```
+POST /api/v1/bills
+{
+  "contactResourceId": "<supplier-uuid>",
+  "saveAsDraft": false,
+  "reference": "BILL-MISSING-001",
+  "valueDate": "2025-01-15",
+  "dueDate": "2025-02-14",
+  "lineItems": [{
+    "name": "Office supplies — Jan 2025",
+    "unitPrice": 850.00,
+    "quantity": 1,
+    "accountResourceId": "<expense-account-uuid>",
+    "taxProfileResourceId": "<tax-profile-uuid>"
+  }]
+}
+```
+
+Or use Jaz Magic if you have the document:
+
+```
+POST /api/v1/magic/createBusinessTransactionFromAttachment
+Content-Type: multipart/form-data
+
+Fields:
+  - sourceFile: <PDF of the missing bill>
+  - businessTransactionType: "BILL"
+  - sourceType: "FILE"
+```
+
+### Difference Type 2: Duplicate payments
+
+You paid the same bill twice, or the supplier hasn't credited a payment you made.
+
+**How to check:** Look for two payments with the same amount and similar dates against different bills from the same supplier.
+
+**Resolution:**
+- If genuinely paid twice → request a refund or credit note from the supplier
+- If the supplier hasn't recorded your payment → send them the bank transfer reference/proof
+
+### Difference Type 3: Timing differences
+
+The most common and least worrying type. Your payment was made on Jan 30 but the supplier didn't record it until Feb 3.
+
+**Resolution:** No action needed — these resolve themselves in the next period. Note them as reconciling items.
+
+### Difference Type 4: Pricing discrepancies
+
+The supplier's invoice amount differs from what you expected (wrong unit price, quantity, or missing discount).
+
+**Resolution:**
+- Contact the supplier to clarify
+- If they agree to the correction → request a supplier credit note
+- Enter the credit note when received:
+
+```
+POST /api/v1/supplier-credit-notes
+{
+  "contactResourceId": "<supplier-uuid>",
+  "saveAsDraft": false,
+  "reference": "SCN-DISPUTE-001",
+  "valueDate": "2025-01-31",
+  "lineItems": [{
+    "name": "Price correction — Invoice #12345",
+    "unitPrice": 150.00,
+    "quantity": 1,
+    "accountResourceId": "<expense-account-uuid>",
+    "taxProfileResourceId": "<tax-profile-uuid>"
+  }]
+}
+```
+
+### Difference Type 5: Bills in your books, not in supplier statement
+
+You have a bill entered, but the supplier doesn't show it.
+
+**Common causes:**
+- You entered a bill from a pro-forma/estimate instead of the actual invoice
+- The bill was entered under the wrong supplier contact
+- The supplier issued a credit note you haven't processed
+
+**Resolution:** Investigate and either void the incorrect bill or request clarification from the supplier.
+
+---
+
+## Phase 5: Verification
+
+### Step 7: Re-check after adjustments
+
+After entering missing bills, credit notes, and resolving discrepancies:
+
+```
+POST /api/v1/bills/search
+{
+  "filter": {
+    "contactResourceId": { "eq": "<supplier-uuid>" },
+    "status": { "eq": "POSTED" },
+    "balanceAmount": { "gt": 0 }
+  },
+  "sort": { "sortBy": ["dueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+Sum `balanceAmount` again. The difference between this and the supplier's statement should now be explainable entirely by timing differences.
+
+### Step 8: Verify AP aging
+
+```
+POST /api/v1/generate-reports/ap-report
+{ "endDate": "2025-01-31" }
+```
+
+**What to check:**
+- Supplier's balance reflects all adjustments
+- Total AP still ties to the Accounts Payable control account on the trial balance
+
+---
+
+## Supplier Recon Checklist (Quick Reference)
+
+| # | Step | Phase | What |
+|---|------|-------|------|
+| 1 | Find supplier contact | Setup | Search contacts with supplier=true |
+| 2 | List bills for period | Your records | Bills by contact + date range |
+| 3 | List payments for period | Your records | Payment records per bill |
+| 4 | List credit notes | Your records | Supplier credit notes in period |
+| 5 | Get your AP balance | Compare | Sum of unpaid bill balances |
+| 6 | Compare to supplier statement | Compare | External document comparison |
+| — | Missing bills | Resolve | Enter missing, use Jaz Magic |
+| — | Duplicate payments | Resolve | Request refund/credit |
+| — | Timing differences | Resolve | Note only, resolves next period |
+| — | Pricing discrepancies | Resolve | Request supplier credit note |
+| — | Phantom bills | Resolve | Investigate and void if needed |
+| 7 | Re-check balance | Verify | Should match or explain difference |
+| 8 | Verify AP aging | Verify | Total AP ties to trial balance |
+
+---
+
+## Common Discrepancy Types (Summary)
+
+| Type | Direction | Action |
+|------|-----------|--------|
+| Missing bill | You owe more than your books show | Enter the bill |
+| Duplicate payment | You've overpaid | Request refund or credit |
+| Timing difference | Payment in transit | No action, resolves next period |
+| Price discrepancy | Amount disagrees | Request credit note or re-invoice |
+| Phantom bill | Your books show more than supplier | Investigate, void if error |
+| Unapplied credit | Credit note not yet applied | Apply to outstanding bill |
+
+---
+
+## Tips for SMBs
+
+**Do this quarterly at minimum, monthly for high-volume suppliers.** Most supplier disputes become much harder to resolve after 90 days because people forget the details and documents get lost.
+
+**Request statements proactively.** Don't wait for the supplier to send one — email their accounts department at the start of each quarter requesting a statement for the prior period. Many suppliers have online portals where you can download statements on demand.
+
+**The most common issue is missing bills.** In our experience, 80% of supplier recon differences are bills you haven't entered yet. The fix is process, not technology — create a shared inbox or folder for bills and check it daily.
+
+**GST implications of discrepancies.** If you discover missing bills during reconciliation, the input tax claim on those bills belongs to the quarter the bill is dated, not when you entered it. If you've already filed the GST return for that quarter, you may need to adjust in the next return or file a voluntary disclosure.