jaz-cli 2.7.0 → 2.8.0

package/assets/skills/jobs/references/gst-vat-filing.md

@@ -0,0 +1,250 @@
+# GST/VAT Filing Preparation
+
+Prepare your GST/VAT return by generating the tax ledger, reviewing output and input tax, identifying errors, and producing the filing summary. This job does NOT file the return for you — it produces the numbers and supporting detail you need to file accurately via IRAS myTax Portal (SG) or the equivalent authority.
+
+**CLI:** `jaz jobs gst-vat --period 2025-Q1 [--json]`
+
+---
+
+## Background: SG GST Basics
+
+| Item | Detail |
+|------|--------|
+| **Current rate** | 9% (effective Jan 1, 2024) |
+| **Filing frequency** | Quarterly (most SMBs) or monthly (if approved) |
+| **Due date** | 1 month after the end of the quarter (e.g., Q1 Jan-Mar due Apr 30) |
+| **Return form** | GST F5 (standard) or GST F7 (group registration) |
+| **Penalty** | 5% surcharge on unpaid tax + $200/month late filing penalty |
+
+**Tax codes in Jaz (SG defaults):**
+
+| Code | Description | Rate |
+|------|-------------|------|
+| SR | Standard-Rated Supplies (output tax) | 9% |
+| TX | Taxable Purchases (input tax) | 9% |
+| ZR | Zero-Rated Supplies | 0% |
+| ES | Exempt Supplies | 0% |
+| OS | Out-of-Scope Supplies | 0% |
+| EP | Exempt Purchases | 0% |
+| IM | Import of Goods (subject to GST) | 9% |
+
+---
+
+## Phase 1: Generate the Tax Ledger
+
+The tax ledger is your primary working paper. It lists every transaction that has a tax component.
+
+### Step 1: Generate tax ledger for the quarter
+
+```
+POST /api/v1/generate-reports/vat-ledger
+{ "startDate": "2025-01-01", "endDate": "2025-03-31" }
+```
+
+**What you get:** Every invoice, bill, credit note, and journal with a tax profile attached — grouped by tax code, showing gross amount, tax amount, and net amount.
+
+### Step 2: Export for offline review (optional)
+
+```
+POST /api/v1/data-exports/vat-ledger
+{ "startDate": "2025-01-01", "endDate": "2025-03-31" }
+```
+
+This gives you the Excel/CSV version for spreadsheet review.
+
+---
+
+## Phase 2: Review Output Tax (Sales GST Collected)
+
+Output tax is the GST you charged customers on your sales. This is what you owe IRAS.
+
+### Step 3: Cross-reference invoices to tax ledger
+
+```
+POST /api/v1/invoices/search
+{
+  "filter": {
+    "status": { "eq": "POSTED" },
+    "valueDate": { "between": ["2025-01-01", "2025-03-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**What to check:**
+- Total standard-rated sales (SR) on the tax ledger matches total invoiced amount at 9%
+- Zero-rated sales (ZR) have proper documentation (export evidence, international service proof)
+- Exempt sales (ES) are correctly classified (financial services, residential property, etc.)
+- Customer credit notes are deducted from output tax (they reduce your GST liability)
+
+### Step 4: Check for missing tax profiles
+
+Look for invoices with no tax profile — these won't appear on the tax ledger and could mean under-declared output tax.
+
+```
+POST /api/v1/cashflow-transactions/search
+{
+  "filter": {
+    "businessTransactionType": { "eq": "SALE" },
+    "valueDate": { "between": ["2025-01-01", "2025-03-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+Compare the count and total to the invoices search above. Discrepancies may indicate missing tax codes.
+
+---
+
+## Phase 3: Review Input Tax (Purchases GST Paid)
+
+Input tax is the GST you paid on business purchases. This is what you can claim back from IRAS.
+
+### Step 5: Cross-reference bills to tax ledger
+
+```
+POST /api/v1/bills/search
+{
+  "filter": {
+    "status": { "eq": "POSTED" },
+    "valueDate": { "between": ["2025-01-01", "2025-03-31"] }
+  },
+  "sort": { "sortBy": ["valueDate"], "order": "ASC" },
+  "limit": 1000
+}
+```
+
+**What to check:**
+- Total taxable purchases (TX) on the tax ledger matches total bills with 9% GST
+- Supplier credit notes are deducted from input tax claims
+- No claims on exempt purchases (EP) — these should not have claimable GST
+
+### Step 6: Identify blocked input tax (SG-specific)
+
+Certain purchases have GST that CANNOT be claimed even though the supplier charged it. These are "blocked" under the GST Act:
+
+| Blocked Category | Examples |
+|-----------------|----------|
+| **Club subscription fees** | Country clubs, social clubs |
+| **Medical/accident insurance** | Employee medical insurance (unless contractual) |
+| **Medical expenses** | GP visits, dental, specialist |
+| **Family benefits** | Housing, school fees, holiday passage |
+| **Motor vehicle expenses** | Purchase, maintenance, fuel for non-commercial vehicles |
+| **Entertainment** | Client entertainment, staff entertainment (> $50/person) |
+
+**Conditional:** Only relevant if your business has expenses in these categories. Most SMBs will have at least motor vehicle and entertainment expenses to review.
+
+**Action:** Ensure blocked input tax items are coded to a non-claimable tax code (EP or no tax profile), NOT TX. If they're coded as TX, they'll inflate your input tax claim and trigger IRAS scrutiny.
+
+---
+
+## Phase 4: Error Checks
+
+### Step 7: Check for common GST errors
+
+Run these checks against your tax ledger data:
+
+**1. Zero-rated sales without documentation:**
+- Every ZR sale needs export evidence (bill of lading, airway bill) or proof of international service
+- IRAS can reclassify ZR to SR (9%) on audit if documentation is missing
+
+**2. Exempt supplies miscoded as standard-rated:**
+- Financial services, residential rental, sale of residential property are exempt (ES)
+- If coded as SR, you've over-declared output tax and customers were overcharged
+
+**3. Input tax claimed on non-business purchases:**
+- Personal purchases through the business account with GST claimed
+- Capital items used partly for non-business purposes (apportion the claim)
+
+**4. Timing errors:**
+- Invoice dated in Q1 but goods/services delivered in Q2 (tax point = earlier of invoice date or payment date)
+- Supplier bill received in Q2 but dated Q1 — claim in the quarter of the tax invoice date
+
+**5. FX transactions:**
+- GST on FX transactions is calculated on the SGD equivalent at the transaction date rate
+- Verify FX invoices/bills show the correct SGT amount for GST purposes
+
+---
+
+## Phase 5: GST Return Summary
+
+### Step 8: Compile the GST F5 box mapping
+
+Map your tax ledger totals to the IRAS GST F5 return boxes:
+
+| Box | Description | Source |
+|-----|-------------|--------|
+| **Box 1** | Total value of standard-rated supplies | SR gross amount from tax ledger |
+| **Box 2** | Total value of zero-rated supplies | ZR gross amount from tax ledger |
+| **Box 3** | Total value of exempt supplies | ES gross amount from tax ledger |
+| **Box 4** | Total value of supplies (Box 1 + 2 + 3) | Sum |
+| **Box 5** | Total value of taxable purchases | TX + IM gross amount from tax ledger |
+| **Box 6** | Output tax due (Box 1 x 9%) | SR tax amount from tax ledger |
+| **Box 7** | Input tax and refunds claimed | TX + IM tax amount from tax ledger (minus blocked items) |
+| **Box 8** | Net GST to pay/claim (Box 6 - Box 7) | If positive = pay IRAS. If negative = refund claim. |
+
+### Step 9: Generate supporting reports
+
+```
+POST /api/v1/generate-reports/profit-and-loss
+{ "primarySnapshotDate": "2025-03-31", "secondarySnapshotDate": "2025-01-01" }
+```
+
+```
+POST /api/v1/generate-reports/trial-balance
+{ "startDate": "2025-01-01", "endDate": "2025-03-31" }
+```
+
+**What to check:**
+- GST Receivable (input tax) and GST Payable (output tax) accounts on the trial balance should reconcile to your Box 6 and Box 7 amounts
+- Revenue on P&L should be consistent with Box 1 + Box 2 + Box 3 (total supplies)
+
+---
+
+## Phase 6: Export and File
+
+### Step 10: Export the tax ledger for records
+
+```
+POST /api/v1/data-exports/vat-ledger
+{ "startDate": "2025-01-01", "endDate": "2025-03-31" }
+```
+
+Keep this export as your supporting workpaper. IRAS can request transaction-level detail on audit.
+
+**Filing:** Log into IRAS myTax Portal > GST > File GST Return (F5). Enter the box amounts from Step 8. Submit before the due date.
+
+---
+
+## GST Filing Checklist (Quick Reference)
+
+| # | Step | Phase | Conditional |
+|---|------|-------|-------------|
+| 1 | Generate tax ledger | Generate | Always |
+| 2 | Export for offline review | Generate | Optional |
+| 3 | Cross-reference invoices | Output tax | Always |
+| 4 | Check missing tax profiles | Output tax | Always |
+| 5 | Cross-reference bills | Input tax | Always |
+| 6 | Identify blocked input tax | Input tax | If blocked categories exist |
+| 7 | Run error checks | Errors | Always |
+| 8 | Compile F5 box mapping | Summary | Always |
+| 9 | Generate supporting reports | Summary | Always |
+| 10 | Export and file | File | Always |
+
+---
+
+## Common SMB GST Mistakes
+
+1. **Claiming input tax on blocked items** — Motor vehicle fuel and entertainment are the most common. IRAS audits specifically look for these.
+
+2. **Late registration** — If your taxable turnover exceeds $1M in any 12-month period (or you expect it to in the next 12 months), you must register within 30 days. Penalties apply retroactively.
+
+3. **Wrong tax point** — GST is due on the earlier of: invoice date, payment date, or delivery date. Backdating invoices to shift GST to a later quarter is a compliance risk.
+
+4. **Not claiming input tax on imports** — If you import goods and pay GST at customs, you CAN claim this as input tax. Many SMBs forget to include import GST in their returns.
+
+5. **Mixing exempt and taxable supplies** — If you make both exempt and taxable supplies, you must apportion input tax. Only the portion attributable to taxable supplies is claimable. Use the standard method (revenue ratio) unless IRAS has approved a special method.
+
+6. **Filing after the deadline** — Even if you owe nothing, late filing triggers a $200/month penalty. Set a calendar reminder for the 15th of the month after quarter-end to give yourself buffer time.

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