jaz-cli 2.6.0 → 2.8.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-version: 2.6.0
+version: 2.8.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.
@@ -22,7 +22,7 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 
 **Base URL**: `https://api.getjaz.com`
 **Auth**: `x-jk-api-key: <key>` header on every request — key has `jk-` prefix (e.g., `jk-a1b2c3...`). NOT `Authorization: Bearer` or `x-api-key`.
-**Content-Type**: `application/json` for all POST/PUT/PATCH
+**Content-Type**: `application/json` for all POST/PUT/PATCH (except multipart endpoints: `createBusinessTransactionFromAttachment` FILE mode, `importBankStatementFromAttachment`, and attachment uploads)
 **All paths are prefixed**: `/api/v1/` (e.g., `https://api.getjaz.com/api/v1/invoices`)
 
 ## Critical Rules
@@ -129,6 +129,14 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 55. **Scheduled endpoints support date aliases** — `txnDateAliases` middleware (mapping `issueDate`/`date` → `valueDate`) now applies to all scheduled create/update endpoints: `POST/PUT /scheduled/invoices`, `POST/PUT /scheduled/bills`, `POST/PUT /scheduled/journals`, `POST/PUT /scheduled/subscriptions`.
 56. **Kebab-case URL aliases** — `capsuleTypes` endpoints also accept kebab-case paths: `/capsule-types` (list, search, CRUD). `moveTransactionCapsules` also accepts `/move-transaction-capsules`. Both camelCase and kebab-case work identically.
 
+### Jaz Magic — Extraction & Autofill
+57. **When the user starts from an attachment, always use Jaz Magic** — if the input is a PDF, JPG, or any document image (invoice, bill, receipt), the correct path is `POST /magic/createBusinessTransactionFromAttachment`. Do NOT manually construct a `POST /invoices` or `POST /bills` payload from an attachment — Jaz Magic handles the entire extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, CoA auto-mapping via ML learning, and draft creation with all fields pre-filled. Only use `POST /invoices` or `POST /bills` when building transactions from structured data (JSON, CSV, database rows) where the fields are already known.
+58. **Two upload modes with different content types** — `sourceType: "FILE"` requires **multipart/form-data** with `sourceFile` blob (JSON body fails with 400 "sourceFile is a required field"). `sourceType: "URL"` accepts **application/json** with `sourceURL` string. The OAS only documents URL mode — FILE mode (the common case) is undocumented.
+59. **Three required fields**: `sourceFile` (multipart blob — NOT `file`), `businessTransactionType` (`"INVOICE"` or `"BILL"` only — `EXPENSE` rejected), `sourceType` (`"FILE"` or `"URL"`). All three are validated server-side.
+60. **Response maps transaction types**: Request `BILL` → response `businessTransactionType: "PURCHASE"`. Request `INVOICE` → response `businessTransactionType: "SALE"`. S3 paths follow: `/purchases/` vs `/sales/`.
+61. **Extraction is asynchronous** — the API response is immediate (file upload confirmation only). The actual Magic pipeline — OCR, line item extraction, contact matching, CoA learning, and autofill — runs asynchronously. The `subscriptionFBPath` in the response (e.g., `magic_transactions/{orgId}/purchase/{fileId}`) is a Firebase Realtime Database path for subscribing to extraction status updates.
+62. **Accepts PDF and JPG/JPEG** — both file types confirmed working. Handwritten documents are accepted at upload stage (extraction quality varies). `fileType` in response reflects actual format: `"PDF"`, `"JPEG"`.
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:
@@ -154,6 +162,8 @@ The backend DX overhaul is live. Key improvements now available:
 
 ## Recommended Client Patterns
 
+- **Starting from an attachment?** → Use Jaz Magic (`POST /magic/createBusinessTransactionFromAttachment`). Never manually parse a PDF/JPG to construct `POST /invoices` or `POST /bills` — let the extraction & autofill pipeline handle it.
+- **Starting from structured data?** → Use `POST /invoices` or `POST /bills` directly with the known field values.
 - **Serialization (Python)**: `model_dump(mode="json", by_alias=True, exclude_unset=True, exclude_none=True)`
 - **Field names**: All request bodies use camelCase
 - **Date serialization**: Python `date` type → `YYYY-MM-DD` strings

package/assets/skills/api/references/dependencies.md

@@ -54,8 +54,9 @@ Resources MUST be created in this order. Steps at the same level can run in para
 - `POST /items` → create items (needs CoA + tax profile IDs from Levels 0-1)
 
 ### Level 3: Transactions (parallel)
-- `POST /invoices` → create invoices (needs contacts + CoA + tax profiles)
-- `POST /bills` → create bills (same deps, can embed payments)
+- `POST /magic/createBusinessTransactionFromAttachment` → **starting from an attachment (PDF/JPG)?** Use Jaz Magic — extraction & autofill creates a draft invoice or bill with all fields pre-filled. See SKILL.md Rules 57-62.
+- `POST /invoices` → create invoices from structured data (needs contacts + CoA + tax profiles)
+- `POST /bills` → create bills from structured data (same deps, can embed payments)
 - `POST /journals` → create journal entries (needs CoA)
 - `POST /cash-in-journals` → cash receipts (needs bank account from CoA)
 - `POST /cash-out-journals` → cash payments (needs bank account from CoA)

package/assets/skills/api/references/endpoints.md

@@ -790,6 +790,84 @@ Valid `datatypeCode`: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `LINK`.
 
 ---
 
+## 14g. Jaz Magic — Extraction & Autofill
+
+### POST /api/v1/magic/createBusinessTransactionFromAttachment
+
+**When the user starts from an attachment (PDF, JPG, document image), this is the endpoint to use.** Do not manually parse files to construct `POST /invoices` or `POST /bills` — Jaz Magic handles the full extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, and CoA auto-mapping via ML learning. Creates a complete draft transaction with all fields pre-filled. Use `POST /invoices` or `POST /bills` only when building from structured data where the fields are already known.
+
+Processing is **asynchronous** — the API response confirms file upload immediately. The extraction pipeline runs server-side and pushes status updates via Firebase Realtime Database.
+
+**Two modes** — content type depends on `sourceType`:
+
+#### FILE mode (multipart/form-data) — most common
+
+```
+POST /api/v1/magic/createBusinessTransactionFromAttachment
+Content-Type: multipart/form-data
+
+Fields:
+  - sourceFile: PDF or JPG file blob (NOT "file")
+  - businessTransactionType: "INVOICE" or "BILL" (NOT "EXPENSE")
+  - sourceType: "FILE"
+```
+
+```json
+/ Response (201):
+{
+  "data": {
+    "businessTransactionType": "PURCHASE",
+    "filename": "NB64458.pdf",
+    "invalidFiles": [],
+    "validFiles": [{
+      "subscriptionFBPath": "magic_transactions/{orgId}/purchase/{fileId}",
+      "errorCode": null,
+      "errorMessage": null,
+      "fileDetails": {
+        "fileId": "6e999313b8b53ccef0757394ee6c7e6a",
+        "fileType": "PDF",
+        "fileURL": "https://s3.ap-southeast-1.amazonaws.com/.../{resourceId}.PDF",
+        "fileName": "NB64458.pdf"
+      }
+    }]
+  }
+}
+```
+
+#### URL mode (application/json) — for remote files
+
+```json
+/ Request:
+POST /api/v1/magic/createBusinessTransactionFromAttachment
+Content-Type: application/json
+
+{
+  "businessTransactionType": "BILL",
+  "sourceType": "URL",
+  "sourceURL": "https://example.com/invoice.pdf"
+}
+
+/ Response: same shape as FILE mode
+```
+
+**What Jaz Magic extracts and autofills:**
+- Line items (description, quantity, unit price, amounts)
+- Contact name and details (matched against existing contacts)
+- Chart of Accounts mapping (ML-based learning from past transactions)
+- Tax amounts and profiles
+- Document reference numbers, dates, currency
+
+**Key gotchas:**
+- `sourceFile` is the field name (NOT `file`) — same pattern as bank statement endpoint
+- Only `INVOICE` and `BILL` accepted — `EXPENSE` returns 422
+- Response maps types: `INVOICE` → `SALE`, `BILL` → `PURCHASE`
+- JSON body with `sourceType: "FILE"` always fails (400) — MUST use multipart
+- `subscriptionFBPath` is the Firebase path for tracking extraction progress
+- All three fields (`sourceFile`/`sourceURL`, `businessTransactionType`, `sourceType`) are required — omitting any returns 422
+- File types confirmed: PDF, JPG/JPEG (handwritten documents accepted — extraction quality varies)
+
+---
+
 ## 15. Bank Records
 
 ### POST /api/v1/magic/importBankStatementFromAttachment (multipart)

package/assets/skills/api/references/feature-glossary.md

@@ -14,7 +14,7 @@ Key capabilities: draft/approval workflows, multi-currency (auto-fetch ECB rates
 
 If payment date equals invoice date, it's recorded as a cash transaction (not AR). Transaction fees are deducted from cash received. RGL = `(Invoice payment / Transaction Rate) - (Cash received / Payment Rate)`.
 
-**API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `PUT /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`
+**API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `PUT /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
 
 ---
 
@@ -26,7 +26,7 @@ Key capabilities: bill receipts (short-form template creating bill + payment tog
 
 Transaction fees are added to cash spent (not deducted like invoices). RGL = `(Cash spent / Payment rate) - (Bill payment / Transaction rate)`.
 
-**API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `PUT /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`
+**API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `PUT /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
 
 ---
 
@@ -173,9 +173,9 @@ Fixed assets lock their linked line items — cannot edit account, amounts, or e
 
 **Agent Builder**: Configure custom AI agents in Settings > Agent Builder with name, email (a-z, 0-9, + symbol), and workflow preferences.
 
-**Jaz Magic**: Contact-level setting controlling auto-extraction behavior — line items (detailed extraction), summary totals (single amount), or none. Up to 10 images can be merged into a single PDF.
+**Jaz Magic**: The extraction & autofill engine. When users start from an attachment (PDF, JPG, document image), Jaz Magic is the correct path — it handles OCR, line item detection, contact matching, and CoA auto-mapping via ML learning, producing a complete draft transaction. Contact-level settings control extraction behavior: line items (detailed extraction), summary totals (single amount), or none. Up to 10 images can be merged into a single PDF. **Do not manually parse attachments to construct `POST /invoices` or `POST /bills` — always use Jaz Magic when the input is a file.**
 
-**API**: `POST /magic/createBusinessTransactionFromAttachment` (OCR PDF → draft transaction), `POST /magic/importBankStatementFromAttachment`, `PUT /invoices/magic-update`, `PUT /bills/magic-update`, `PUT /journals/magic-update`, `GET /invoices/magic-search`, `GET /bills/magic-search` (all magic endpoints use `x-magic-api-key`)
+**API**: `POST /magic/createBusinessTransactionFromAttachment` (**attachment → draft transaction** — the primary endpoint for file-based creation), `POST /magic/importBankStatementFromAttachment` (bank statements), `PUT /invoices/magic-update`, `PUT /bills/magic-update`, `PUT /journals/magic-update`, `GET /invoices/magic-search`, `GET /bills/magic-search` (all magic endpoints use `x-magic-api-key`)
 
 ---
 

package/assets/skills/api/references/field-map.md

@@ -260,6 +260,23 @@ When POSTing, `classificationType` must be one of these exact strings (same as `
 
 ---
 
+## Jaz Magic — Extraction & Autofill
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `file` | `sourceFile` | Multipart blob — same pattern as bank statement |
+| `type: "BILL"` | `businessTransactionType: "BILL"` | Request accepts `INVOICE` or `BILL` only |
+| Response `"BILL"` | Response `"PURCHASE"` | Response maps: `BILL` → `PURCHASE`, `INVOICE` → `SALE` |
+| JSON body | multipart/form-data | FILE mode requires multipart — JSON returns 400 |
+| Sync response | Async extraction | Response = upload confirmation; extraction & autofill run async |
+| `status` field | `subscriptionFBPath` | Firebase path for tracking extraction progress |
+
+**Content-Type depends on sourceType:**
+- `sourceType: "FILE"` → `Content-Type: multipart/form-data` (MUST use multipart)
+- `sourceType: "URL"` → `Content-Type: application/json` (JSON body works)
+
+---
+
 ## Bank Records
 
 | What You'd Guess | Actual API Field | Notes |

package/assets/skills/api/references/full-api-surface.md

@@ -386,7 +386,7 @@
 
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/magic/createBusinessTransactionFromAttachment` | OCR: Convert PDF → transaction |
+| POST | `/magic/createBusinessTransactionFromAttachment` | **Jaz Magic: Extraction & Autofill.** Upload PDF/JPG → full extraction pipeline (OCR, line items, contact matching, CoA ML learning) → draft invoice or bill with all fields autofilled. FILE mode = multipart (`sourceFile` blob), URL mode = JSON (`sourceURL`). Async — returns `subscriptionFBPath` for tracking extraction progress. Request `INVOICE` → response `SALE`, `BILL` → `PURCHASE`. |
 | POST | `/magic/importBankStatementFromAttachment` | Convert bank statement → entries |
 | PUT | `/invoices/magic-update` | AI-enhanced invoice update |
 | PUT | `/bills/magic-update` | AI-enhanced bill update |

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conversion
-version: 2.6.0
+version: 2.8.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,104 @@
+---
+name: jobs
+version: 2.8.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

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