jaz-cli 2.7.0 → 2.9.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-version: 2.7.0
+version: 2.9.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.9.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,161 @@
+---
+name: jobs
+version: 2.9.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
+
+## Tax Computation — Singapore Form C-S
+
+Corporate income tax computation for Singapore-incorporated companies. The AI agent acts as the **tax wizard** — pulling data from Jaz, classifying GL items, asking the user targeted questions, and assembling the input for the CLI computation engine.
+
+**Scope:** Form C-S (revenue ≤ $5M, 18 fields) and Form C-S Lite (revenue ≤ $200K, 6 fields). NOT Form C.
+
+### How It Works
+
+```
+┌──────────────────────────────┐     ┌───────────────────────────────┐
+│  Reference Docs (this skill) │     │  CLI Computation Engine        │
+│  "The Wizard Script"         │     │  jaz tax sg-cs [--json]       │
+│  - Guides AI agent           │     │  - Pure deterministic math     │
+│  - API calls to make         │     │  - Accepts structured JSON     │
+│  - Questions to ask user     │     │  - Outputs workpaper +         │
+│  - Classification rules      │     │    Form C-S fields +           │
+│  - SG tax rules reference    │     │    carry-forwards              │
+└──────────────┬───────────────┘     └───────────────┬───────────────┘
+               │                                      │
+               └────────►  AI Agent  ◄────────────────┘
+                    1. Reads reference docs
+                    2. Pulls Jaz API data
+                    3. Classifies GL items
+                    4. Asks user questions
+                    5. Assembles input JSON
+                    6. Runs jaz tax sg-cs
+                    7. Presents results + filing guidance
+```
+
+### CLI Commands
+
+```bash
+# Full computation (JSON input from wizard or file)
+jaz tax sg-cs --input tax-data.json [--json]
+echo '{ "ya": 2026, ... }' | jaz tax sg-cs --json
+
+# Simple mode (manual flags)
+jaz tax sg-cs --ya 2026 --revenue 500000 --profit 120000 --depreciation 15000 --exemption pte [--json]
+
+# Capital allowance schedule (standalone)
+jaz tax sg-ca --input assets.json [--json]
+jaz tax sg-ca --ya 2026 --cost 50000 --category general --acquired 2024-06-15 [--json]
+```
+
+### Tax Reference Files
+
+- **[references/sg-tax/overview.md](./references/sg-tax/overview.md)** — SG CIT framework: 17% rate, YA concept, Form C-S eligibility, key deadlines
+- **[references/sg-tax/form-cs-fields.md](./references/sg-tax/form-cs-fields.md)** — All 18 Form C-S + 6 C-S Lite fields with IRAS labels and CLI mapping
+- **[references/sg-tax/wizard-workflow.md](./references/sg-tax/wizard-workflow.md)** — Step-by-step wizard procedure for AI agents (the main playbook)
+- **[references/sg-tax/data-extraction.md](./references/sg-tax/data-extraction.md)** — How to pull P&L, TB, GL, FA data from Jaz API for tax purposes
+- **[references/sg-tax/add-backs-guide.md](./references/sg-tax/add-backs-guide.md)** — Classification guide: which expenses are non-deductible
+- **[references/sg-tax/capital-allowances-guide.md](./references/sg-tax/capital-allowances-guide.md)** — CA rules per asset category with IRAS sections
+- **[references/sg-tax/ifrs16-tax-adjustment.md](./references/sg-tax/ifrs16-tax-adjustment.md)** — IFRS 16 lease reversal procedure
+- **[references/sg-tax/enhanced-deductions.md](./references/sg-tax/enhanced-deductions.md)** — R&D, IP, donations 250%, S14Q renovation
+- **[references/sg-tax/exemptions-and-rebates.md](./references/sg-tax/exemptions-and-rebates.md)** — SUTE, PTE, CIT rebate schedule
+- **[references/sg-tax/losses-and-carry-forwards.md](./references/sg-tax/losses-and-carry-forwards.md)** — Set-off order, loss/CA/donation carry-forward rules

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