jaz-clio 5.4.4 → 5.4.6

package/README.md

@@ -18,8 +18,8 @@ Requires **Node.js 18+** ([nodejs.org](https://nodejs.org)). Also fully compatib
 ## Contents
 
 - [Three Ways In](#three-ways-in) — CLI, MCP, Skills
-- [CLI](#cli) — 53 command groups
-- [MCP Server](#mcp-server) — 265 tools for AI agents
+- [CLI](#cli) — 55 command groups
+- [MCP Server](#mcp-server) — 274 tools for AI agents
 - [Skills](#skills) — Teach any AI the Jaz API
 - [Setup](#setup) — Auth, multi-org, automation
 
@@ -27,7 +27,7 @@ Requires **Node.js 18+** ([nodejs.org](https://nodejs.org)). Also fully compatib
 
 | | What happens | Try it |
 |---|---|---|
-| **CLI** | 53 command groups, every accounting operation | `clio invoices list` |
+| **CLI** | 55 command groups, every accounting operation | `clio invoices list` |
 | **MCP** | Plug into Claude Code, Cursor, Codex, Copilot | `clio mcp` |
 | **Skills** | Teach any AI tool the Jaz API | `clio init` |
 
@@ -48,7 +48,7 @@ clio practice onboard --name "Acme Pte Ltd" --fy-end 12-31 --gst quarterly
 clio practice create-engagement acme-pte-ltd --type monthly-close --period 2026-03
 ```
 
-54 command groups. 16 report types. 13 calculators. 12 job playbooks. New in v5.2.0: practitioner workspace (`clio practice`). Every command supports `--json`. Run `clio --help` for the full list.
+55 command groups. 16 report types. 13 calculators. 12 job playbooks. New in v5.2.0: practitioner workspace (`clio practice`). Every command supports `--json`. Run `clio --help` for the full list.
 
 ---
 

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.4.4
+version: 5.4.6
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 141 production gotchas, error

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.4.4
+version: 5.4.6
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -8,6 +8,7 @@ description: >-
   command groups, auth precedence, output formats, entity resolution, and common
   workflow patterns. Also use when the user asks how to use clio, what commands
   are available, or how to automate accounting tasks from the command line.
+  Covers all 55 command groups and 274 agent tools.
 license: MIT
 compatibility: Requires Node.js >= 18.0.0. Install via npm install -g jaz-clio.
 ---
@@ -16,7 +17,7 @@ compatibility: Requires Node.js >= 18.0.0. Install via npm install -g jaz-clio.
 
 > **Audience note:** for power users and CI/automation. Most practitioners using Claude Desktop or `jaz-practice` workflows can ignore this skill — the practice MCP tools (`practice_*`) cover the day-to-day flows. Load this skill only when you're scripting from a terminal, building shell pipelines, or debugging from `clio --json` output.
 
-You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting platform. 53 command groups, 13 calculators, 12 job blueprints, 265 agent tools. Also fully compatible with Juan Accounting (same API, same endpoints).
+You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting platform. 55 command groups, 13 calculators, 12 job blueprints, 274 agent tools. Also fully compatible with Juan Accounting (same API, same endpoints).
 
 ## When to Use This Skill
 
@@ -33,7 +34,7 @@ You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting pl
 | Need | Skill |
 |------|-------|
 | CLI command syntax, flags, output | **jaz-cli** (this skill) |
-| API field names, error codes, 117 gotchas | **jaz-api** |
+| API field names, error codes, 141 gotchas | **jaz-api** |
 | IFRS transaction recipes (depreciation, leases, loans) | **jaz-recipes** |
 | Month-end close, bank recon, GST filing workflows | **jaz-jobs** |
 | Migration from Xero/QuickBooks/Sage | **jaz-conversion** |
@@ -259,7 +260,7 @@ Sending `lineItems[]` to the FLAT endpoint silently ignores them and creates a $
 
 **Calculators**: `calc` (loan, lease, depreciation, prepaid-expense, deferred-revenue, fx-reval, ecl, provision, fixed-deposit, asset-disposal, accrued-expense, leave-accrual, dividend)
 
-**Jobs**: `jobs` (month-end, quarter-end, year-end, bank-recon, gst-vat, payment-run, credit-control, supplier-recon, audit-prep, fa-review, document-collection, statutory-filing) + tools (match, bank-file, outstanding, ingest, sg-cs, sg-ca)
+**Jobs**: `jobs` (month-end, quarter-end, year-end, bank-recon, gst-vat, payment-run, credit-control, supplier-recon, audit-prep, fa-review, document-collection, statutory-filing) + tools (match, outstanding, ingest, sg-cs, sg-ca)
 
 **Organization**: `org` (info), `org-users`, `auth`
 

package/assets/skills/cli/references/command-catalog.md

@@ -1,6 +1,6 @@
 # Clio Command Catalog
 
-Complete reference for all 53 command groups. Organized by domain.
+Complete reference for all 55 command groups. Organized by domain.
 
 ---
 
@@ -437,7 +437,6 @@ Blueprints are offline (no auth). Tools require auth.
 | `match` | Tool | `--input` (bank records + transactions JSON) |
 | `gst-vat` | Blueprint | `--period`, `--jurisdiction` |
 | `payment-run` | Blueprint | `--date` |
-| `bank-file` | Tool | `--format`, `--input` (generates GIRO/FAST/PayNow file) |
 | `outstanding` | Tool | `--contact`, `--limit` (group outstanding bills) |
 | `credit-control` | Blueprint | `--aging-days` |
 | `supplier-recon` | Blueprint | `--contact` |

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.4.4
+version: 5.4.6
 description: >-
   Use this skill when migrating accounting data into Jaz — importing from Xero,
   QuickBooks, Sage, MYOB, or Excel exports. Covers the full conversion pipeline:
@@ -17,7 +17,9 @@ description: >-
 
 You are performing an **accounting data conversion** — migrating a customer's financial data from their previous accounting software (Xero, QuickBooks, Sage, MYOB, or Excel-based systems) into Jaz.
 
-**This skill provides conversion domain knowledge. For API details (field names, endpoints, gotchas), load the `jaz-api` skill alongside this one.**
+> **Jaz-native, not generic.** The clearing-account pattern, the CoA-bulk-upsert all-or-nothing semantics, the `currencyCode`-string-silently-ignored-on-invoices gotcha, the `bulk_upsert_invoices` PARTIAL_SUCCESS path — every rule in this skill is an opinion shaped by Jaz's specific API behavior, not by generic migration theory. Source-system mapping (Xero, QB, Sage) is included only as input parsing; everything downstream is Jaz-shaped.
+
+**This skill provides Jaz-contextual conversion domain knowledge. For API details (field names, endpoints, gotchas), load the `jaz-api` skill alongside this one.**
 
 **Engagement context:** when this skill is invoked from inside a `jaz-practice` client folder, the onboarding flow (`practice_onboard_client`) loads CLIENT.md to capture FY-end, GST scheme, banking, and the prior firm's name — then routes to this skill for the actual data move. After conversion completes (Step 7 verification), the practitioner closes the onboarding engagement and the recurring engagement cadence (monthly-close / quarterly-gst / annual-statutory) takes over. See `jaz-practice/references/onboarding.md` for the complete sequence.
 

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.4.4
+version: 5.4.6
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,
@@ -16,7 +16,9 @@ compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent t
 
 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.
+> **Jaz-native, not generic.** Every job in this skill names specific Jaz MCP tools (`search_invoices`, `quick_reconcile`, `bulk_finalize_drafts`, `generate_*_blueprint`, `download_export`), Jaz reconciliation modes, and Jaz capsule patterns. It is NOT an interchangeable accounting workflow reference; it is the operating manual for running these processes through the Jaz API surface. When the playbook says "match bank entries", it means call `clio jobs bank-recon match` (the 5-phase cascade matcher built into the CLI), not "use any matching algorithm".
+
+**Jobs combine recipes, calculators, and API calls into complete business processes.** If recipes are ingredients, jobs are the meal. Within a practitioner engagement (`jaz-practice` skill), the engagement-type playbook (`practice/references/<type>.md`) is the canonical end-to-end orchestration — the references in this skill describe the building-block jobs the engagement playbook invokes.
 
 ## When to Use This Skill
 

package/assets/skills/jobs/references/audit-prep.md

@@ -1,319 +1,251 @@
 # 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:** `clio jobs audit-prep --period 2025 [--json]`
+> Compile the report pack + supporting schedules + reconciliations an auditor or tax agent needs to issue an opinion or file a return. Driver tool: `generate_audit_prep_blueprint`.
+
+## Tools, recipes, calculators this job uses
+
+### MCP tools — financial statements
+- **`generate_audit_prep_blueprint`** — used in step 1: emit the phased deliverables list for the period.
+- **`generate_trial_balance(period_end: <FY-end>)`** — step 2: master reconciliation. Every other report ties back to this.
+- **`generate_balance_sheet(period_end: <FY-end>)`** — step 3.
+- **`generate_profit_and_loss(period_start: <FY-start>, period_end: <FY-end>)`** — step 3.
+- **`generate_cashflow(period_start, period_end)`** — step 4.
+- **`generate_equity_movement(period_start, period_end)`** — step 4.
+- **`generate_general_ledger(period_start, period_end, groupBy: 'ACCOUNT')`** — step 5: the auditor's primary working document.
+
+### MCP tools — supporting schedules
+- **`generate_aged_ar(period_end)` / `generate_aged_ap(period_end)`** — step 6.
+- **`generate_bank_recon_summary(period_end)` / `generate_bank_recon_details(period_end)`** — step 7. NON-NEGOTIABLE deliverable.
+- **`generate_bank_balance_summary(period_end)`** — step 7. Cross-reference to bank confirmation letters.
+- **`generate_fa_summary(period_end)` / `generate_fa_recon_summary(period_start, period_end)`** — step 8.
+- **`generate_vat_ledger(period_start, period_end)`** — step 9. Annual total ties to sum of quarterly F5 returns.
+
+### MCP tools — XLSX deliverables
+- **`download_export(exportType: '<type>', startDate, endDate)`** — step 10: pre-signed XLSX URL (~5 min expiry). Per `jaz-api/SKILL.md` rule (data-exports), supported types include `trial-balance`, `profit-and-loss`, `balance-sheet`, `general-ledger`, `ar-report`, `ap-report`, `cashflow`, `analysis-anomalous-bills`, `analysis-anomalous-invoices`, `analysis-cashflow-anomalies`, `analysis-gl-journal-audit`, `analysis-exchange-rate-audit`, `analysis-receivables-customer-risk`, `analysis-cash-expense-health`. The audit-analyses are essential pre-emptive flags for the auditor.
+
+### MCP tools — completeness gates
+- **`search_journals(filter: {status: {eq: 'DRAFT'}, valueDate: {between: [<FY-start>, <FY-end>]}})`** — step 12: must return zero rows before pack hand-off.
+- **`search_invoices(filter: {status: {eq: 'DRAFT'}, valueDate: {between: [<FY-start>, <FY-end>]}})`** — step 12: same gate, sales side.
+- **`search_bills(filter: {status: {eq: 'DRAFT'}, valueDate: {between: [<FY-start>, <FY-end>]}})`** — step 12: same gate, purchases side.
+- **`bulk_finalize_drafts({kind: 'journal', resourceIds: [...]})`** — step 12 fallback: clear residual drafts before pack hand-off.
+- **`update_account(resourceId: <CoA root>, lockDate: <FY-end>)`** — step 12 final: lock the period to prevent backdated entries during fieldwork.
+
+### Calculators (cross-check schedules — no API key needed)
+- **`clio calc loan --principal --rate --term --start-date --json`** — step 8: independent loan amortization for the loan schedule.
+- **`clio calc lease --payment --term --rate --json`** — step 8: IFRS 16 ROU + lease liability schedule.
+- **`clio calc ecl --receivables <json> --json`** — step 8: ECL provision matrix per IFRS 9.
+- **`clio calc fixed-deposit --principal --rate --term --json`** — step 8: FD interest accrual.
+- **`clio calc depreciation --cost --salvage --life --method --json`** — step 8: per-asset depreciation cross-check vs FA register.
+
+### Cross-references
+- Within an engagement: invoked from `practice/references/annual-statutory.md` step 5 (audit-prep is the bridge between year-end close and statutory filing). Practice playbook reads `CLIENT.statutory_audit_required`, `CLIENT.tax_jurisdiction` (`SG` | `PH`), and `CLIENT.fy_end` to scope the deliverables.
+- Sibling jobs: `year-end-close.md` (must complete BEFORE this job — audit-prep assumes books are closed), `statutory-filing.md` (the SG Form C-S / PH ITR step that consumes the pack this job produces — see audit step 13 cross-reference).
+- API rules: `jaz-api/SKILL.md` rule 36 (`endDate` not `startDate` for AR/AP point-in-time reports), rule 38 (pagination for `general-ledger`), rule 52 (response dates are epoch ms).
 
 ---
 
-## Who Needs This
+## 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.
-
----
+| Statutory audit required | Revenue > S$10M, assets > S$10M, or employees > 50 | All stock corporations, paid-up capital > PHP 50K |
+| Tax filing only | All companies file Form C / C-S with IRAS | All companies file ITR with BIR |
+| Compilation by accountant | Small exempt private companies | N/A |
 
-## Phase 1: Core Financial Reports
+Even small exempt SG companies need this pack for the external accountant who prepares the financial statements + Form C-S.
 
-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.
+## Step 1 — Emit blueprint
 
 ```
-POST /api/v1/generate-reports/trial-balance
-{ "startDate": "2025-01-01", "endDate": "2025-12-31" }
+generate_audit_prep_blueprint(period_start: '2025-01-01', period_end: '2025-12-31', currency: <CLIENT.base_currency>, jurisdiction: <CLIENT.tax_jurisdiction>)
 ```
 
-**What the auditor checks:** Debits = Credits (always). Any imbalance indicates a system error.
+Save to `recurring/annual/<period>/audit-prep/blueprint.json`. Blueprint emits jurisdiction-specific deliverable list (SG: TB / BS / P&L / CF / EM / AR aging / AP aging / bank recon / FA register / GST F5 yearly / supporting schedules. PH: same + ITR-specific schedules).
 
-### Step 2: Profit & Loss Statement
+## Step 2 — Trial balance (the master)
 
 ```
-POST /api/v1/generate-reports/profit-and-loss
-{ "primarySnapshotDate": "2025-12-31", "secondarySnapshotDate": "2025-01-01" }
+generate_trial_balance(period_end: '2025-12-31', currency: <CLIENT.base_currency>)
 ```
 
-**Comparative:** If the auditor needs prior year comparison:
+Save to `recurring/annual/<period>/audit-prep/tb.json`. Verify: every report from step 3 onwards must tie back to a TB line.
 
-```
-POST /api/v1/generate-reports/profit-and-loss
-{ "primarySnapshotDate": "2024-12-31", "secondarySnapshotDate": "2024-01-01" }
-```
-
-### Step 3: Balance Sheet
+## Step 3 — Primary financial statements
 
 ```
-POST /api/v1/generate-reports/balance-sheet
-{ "primarySnapshotDate": "2025-12-31" }
+generate_balance_sheet(period_end: '2025-12-31')
+generate_profit_and_loss(period_start: '2025-01-01', period_end: '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
-
+Optional comparative:
 ```
-POST /api/v1/generate-reports/general-ledger
-{ "startDate": "2025-01-01", "endDate": "2025-12-31", "groupBy": "ACCOUNT" }
+generate_profit_and_loss(period_start: '2024-01-01', period_end: '2024-12-31')
+generate_balance_sheet(period_end: '2024-12-31')
 ```
 
-This is the auditor's primary working document. Every transaction, grouped by CoA account, with opening balance, movements, and closing balance.
+Assert: BS Total Assets = Total Liabilities + Total Equity. P&L Net Profit ties to Equity Movement (step 4) `netProfit` line.
 
-### Step 5: Cashflow Statement
+## Step 4 — Cashflow + Equity Movement
 
 ```
-POST /api/v1/generate-reports/cashflow
-{ "primaryStartDate": "2025-01-01", "primaryEndDate": "2025-12-31" }
+generate_cashflow(period_start: '2025-01-01', period_end: '2025-12-31')
+generate_equity_movement(period_start: '2025-01-01', period_end: '2025-12-31')
 ```
 
-Classifies cash movements into Operating, Investing, and Financing activities.
+Cashflow classifies into Operating / Investing / Financing per IAS 7. Equity Movement reconciles opening equity → net profit → dividends → other movements → closing equity. The closing equity must tie to BS step 3 Total Equity.
 
-### Step 6: Equity Movement
+## Step 5 — General Ledger (auditor's working document)
 
 ```
-POST /api/v1/generate-reports/equity-movement
-{ "primarySnapshotStartDate": "2025-01-01", "primarySnapshotEndDate": "2025-12-31" }
+generate_general_ledger(period_start: '2025-01-01', period_end: '2025-12-31', groupBy: 'ACCOUNT')
 ```
 
-Shows opening equity, net profit, dividends, and other movements during the year.
+Per `jaz-api/SKILL.md` rule 38, paginate via `offset` if `totalElements > <page-size>`. Save full GL to `recurring/annual/<period>/audit-prep/gl.json`. Auditor will sample-test from this.
 
----
-
-## Phase 3: Aging Reports
-
-### Step 7: AR Aging (Accounts Receivable)
+## Step 6 — AR / AP aging
 
 ```
-POST /api/v1/generate-reports/ar-report
-{ "endDate": "2025-12-31" }
+generate_aged_ar(period_end: '2025-12-31')
+generate_aged_ap(period_end: '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)
+Use `endDate` not `startDate` (rule 36 — point-in-time snapshot). Assert:
+- `aged_ar.totalOutstanding == TB['Accounts Receivable'].balance` (recoverability gate; auditor tests > 90d aging for ECL adequacy).
+- `aged_ap.totalOutstanding == TB['Accounts Payable'].balance` (completeness gate).
 
+If ECL provision feels inadequate for the > 90d bucket, run the ECL recipe immediately:
 ```
-POST /api/v1/generate-reports/ap-report
-{ "endDate": "2025-12-31" }
+plan_recipe(name: 'ecl', receivables: <aged_ar.buckets converted to ECL input>, ...)
 ```
+And post any top-up provision via `execute_recipe`. This avoids an auditor-proposed adjustment at fieldwork.
 
-**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
+## Step 7 — Bank reconciliation (NON-NEGOTIABLE)
 
 ```
-POST /api/v1/generate-reports/bank-reconciliation-summary
-{ "primarySnapshotDate": "2025-12-31" }
+generate_bank_recon_summary(period_end: '2025-12-31')
+generate_bank_recon_details(period_end: '2025-12-31')
+generate_bank_balance_summary(period_end: '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 each bank account: `unreconciledCount` MUST be 0 OR every unreconciled item has a documented timing-difference explanation in `ENGAGEMENT.risk_areas`. The auditor will request bank confirmation letters DIRECTLY from your banks — `generate_bank_balance_summary` total must reconcile to those letters within tolerance.
 
-**For detailed reconciliation (per bank account):**
+If `unreconciledCount > 0`: halt audit-prep and route back to `bank-recon.md` job. Do NOT hand the pack to the auditor with unreconciled items.
 
-```
-POST /api/v1/generate-reports/bank-reconciliation-details
-{ "primarySnapshotDate": "2025-12-31" }
-```
-
-### Step 10: Bank Balance Summary
+## Step 8 — Fixed assets + supporting schedules
 
 ```
-POST /api/v1/generate-reports/bank-balance-summary
-{ "primarySnapshotDate": "2025-12-31" }
+generate_fa_summary(period_end: '2025-12-31')
+generate_fa_recon_summary(period_start: '2025-01-01', period_end: '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
+Assert: `fa_recon.openingNbv + additions - disposals - depreciation == fa_recon.closingNbv == TB['Fixed Assets'].balance`.
 
+For non-FA-register schedules (loan, lease, ECL, fixed-deposit, prepaid, intercompany), pull the underlying capsules:
 ```
-POST /api/v1/generate-reports/fixed-assets-summary
+search_capsules(filter: {capsuleType: {in: ['Loan Repayment', 'Lease', 'Fixed Deposit', 'Prepaid Expenses', 'Provision']}})
 ```
+For each capsule, run the matching `clio calc <type>` to produce the independent schedule. Save to `recurring/annual/<period>/audit-prep/schedules/<capsule-name>.json`. Auditor uses these to test the IFRS 9 / IFRS 16 / IAS 37 measurements.
 
-Shows all fixed assets: acquisition date, cost, depreciation method, useful life, accumulated depreciation, and net book value.
-
-**For FA reconciliation (movements during the year):**
+## Step 9 — Tax ledger
 
 ```
-POST /api/v1/generate-reports/fixed-assets-recon-summary
+generate_vat_ledger(period_start: '2025-01-01', period_end: '2025-12-31')
 ```
 
-This shows: opening NBV + additions - disposals - depreciation = closing NBV. The auditor reconciles this to the trial balance.
-
----
+For SG: annual total ties to sum of 4 quarterly GST F5 returns. For PH: annual total ties to monthly VAT returns + quarterly summary. Cross-reference: `practice/references/quarterly-gst.md` keeps the per-quarter F5/VAT submissions; the annual reconciliation should already be clean if quarterly-gst engagements ran each period.
 
-## Phase 6: Tax
+## Step 10 — XLSX deliverables (pre-empt auditor requests)
 
-### Step 12: Tax Ledger / GST Summary
+For each report the auditor needs in their workpapers:
 
 ```
-POST /api/v1/generate-reports/vat-ledger
-{ "startDate": "2025-01-01", "endDate": "2025-12-31" }
+download_export(exportType: 'trial-balance', startDate: '2025-01-01', endDate: '2025-12-31', currencyCode: <CLIENT.base_currency>)
 ```
 
-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.
+Returns `{ fileName, fileUrl }` (pre-signed, ~5 min). Download immediately to `recurring/annual/<period>/audit-prep/xlsx/`. Repeat for: `profit-and-loss`, `balance-sheet`, `general-ledger`, `ar-report`, `ap-report`, `cashflow`.
 
----
+**Pre-emptive audit analyses** (run BEFORE handing over the pack — fix what they'd find):
+- `download_export(exportType: 'analysis-anomalous-bills', startDate, endDate)` — flag bills with unusual amounts vs supplier history
+- `download_export(exportType: 'analysis-anomalous-invoices', startDate, endDate)` — same, customer side
+- `download_export(exportType: 'analysis-gl-journal-audit', startDate, endDate)` — flags unbalanced / round-number / large-value journals likely to draw auditor scrutiny
+- `download_export(exportType: 'analysis-exchange-rate-audit', startDate, endDate)` — FX rates outside expected band
+- `download_export(exportType: 'analysis-cash-expense-health', startDate, endDate)` — cash-only expense patterns auditors flag
 
-## Phase 7: Data Exports
+If any analysis surfaces issues, fix BEFORE auditor sees them. Document the corrections in `ENGAGEMENT.md`.
 
-Auditors and tax agents often need the data in Excel format for their own workpapers.
+## Step 11 — Reconciliation checklist
 
-### Step 13: Export all key reports
+Before pack hand-off, assert each row:
 
-```
-POST /api/v1/data-exports/trial-balance
-{ "startDate": "2025-01-01", "endDate": "2025-12-31" }
-```
+| Account | Source | Must match |
+|---------|--------|------------|
+| Cash / Bank | step 7 bank recon | bank confirmation letters |
+| Accounts Receivable | step 6 AR aging | TB AR line |
+| Accounts Payable | step 6 AP aging | TB AP line |
+| Fixed Assets NBV | step 8 FA register | TB FA lines (gross + accumulated dep) |
+| Loan Payable | step 8 loan schedule (per capsule) | TB Loan Payable line |
+| Lease Liability | step 8 lease schedule (per capsule) | TB Lease Liability line |
+| Revenue | step 3 P&L | step 9 VAT ledger Box 1+2+3 totals |
+| GST Receivable / Payable | step 9 VAT ledger | TB GST Control account |
 
-```
-POST /api/v1/data-exports/profit-and-loss
-{ "startDate": "2025-01-01", "endDate": "2025-12-31" }
-```
+Any mismatch beyond `CLIENT.materiality_threshold` halts the pack and routes back to the originating job.
 
-```
-POST /api/v1/data-exports/general-ledger
-{ "startDate": "2025-01-01", "endDate": "2025-12-31", "groupBy": "ACCOUNT" }
-```
+## Step 12 — Completeness gates (final)
 
 ```
-POST /api/v1/data-exports/ar-report
-{ "endDate": "2025-12-31" }
+search_journals(filter: {status: {eq: 'DRAFT'}, valueDate: {between: ['2025-01-01', '2025-12-31']}})
+search_invoices(filter: {status: {eq: 'DRAFT'}, valueDate: {between: ['2025-01-01', '2025-12-31']}})
+search_bills(filter: {status: {eq: 'DRAFT'}, valueDate: {between: ['2025-01-01', '2025-12-31']}})
 ```
 
+ALL three must return zero. If any return rows: collect `resourceId`s, classify (delete vs finalize) per practitioner judgment, and `bulk_finalize_drafts({kind, resourceIds: [...]})` for the keep-set.
+
+Then lock the period:
 ```
-POST /api/v1/data-exports/ap-report
-{ "endDate": "2025-12-31" }
+update_account(resourceId: <CoA root>, lockDate: '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.
+This prevents backdated entries during fieldwork. If the auditor needs to post AJEs, lift the lock temporarily, post, re-lock — do NOT leave it open during fieldwork.
 
-### Step 14: Compile supporting schedules
+## Step 13 — Hand-off to statutory filing
 
-**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
+The pack is now ready. Cross-reference to `practice/references/annual-statutory.md` step 6-7 (statutory filing) which consumes:
+- TB + P&L + BS for Form C-S Lite eligibility check (revenue ≤ S$200K)
+- Audit-analyses for management-letter content
+- Loan / lease / FA schedules for tax computation add-backs
+- VAT ledger annual reconciliation for IRAS Box 1-7 cross-tie
 
-**Loan Schedule:**
-- For each active loan: original principal, interest rate, monthly payment, balance at year-end
-- Extract from the loan capsule GL entries
-- **Calculator:** `clio 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: `clio 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:** `clio calc lease` for the complete schedule
-
-**Fixed Deposit Schedule:**
-- List all fixed deposits: bank, principal, rate, maturity date, accrued interest
-- **Calculator:** `clio calc fixed-deposit` for interest calculations
-
-**Intercompany Balances (if applicable):**
-- Receivables and payables with related parties
-- Must be disclosed separately in financial statements
+The SG Form C-S wizard (`practice/references/annual-statutory.md` step 7) walks the practitioner field-by-field through the C-S form, prefilling from the audit-prep pack.
 
 ---
 
-## 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 |
+## Common error classes and recovery
 
-### 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
+| Source | Error | Recovery |
+|--------|-------|----------|
+| `generate_*` | 422 `period_not_closed` | Year-end close incomplete. Route to `year-end-close.md` first. |
+| `generate_bank_recon_*` | `unreconciledCount > 0` | Route to `bank-recon.md`; do NOT hand pack with this open. |
+| `download_export` | 422 `period_too_long` | GL XLSX rejected for >12 months. Split into per-quarter exports. |
+| `download_export` | 504 timeout | Large org. Re-run with smaller `endDate` range or contact infrastructure team. |
+| `update_account` | 422 `lock_date_in_future` | The CoA `lockDate` must be ≤ `period_end`. Use today if unsure. |
+| Reconciliation | TB AR ≠ AR aging | Likely a mid-period credit-note application missed. `search_customer_credit_notes(filter: {valueDate: {between: ...}})` and verify each was applied via `apply_credit_to_invoice`. |
+| Reconciliation | TB Cash ≠ bank balance summary | Unposted bank journal or unreconciled item. Re-run step 7. |
+| Step 12 gate | Drafts present at year-end | Either clear (finalize) or document in `ENGAGEMENT.risk_areas`. NEVER hand pack with drafts in the audit period. |
 
 ---
 
-## 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
 
-## Tips for SMBs
+- **Start in January for prior FY.** Don't wait for the auditor's request list. Generate the pack in early January; have it ready before the engagement begins. Faster + cheaper audit.
+- **Bank confirmation letters take 2-4 weeks.** Request them from each bank in early January. The auditor will independently request these — yours is for self-verification.
+- **Pre-emptive audit-analyses are the differentiator.** Most accountants hand over the standard pack and wait for queries. Running the 5 `analysis-*` exports proactively in step 10 catches what the auditor would catch — at zero auditor cost.
+- **SG IRAS deadlines:** Form C-S/C: November 30 of the following year. ECI: within 3 months of FY-end. GST F5: 1 month after each quarter-end.
+- **Common audit queries:** "Revenue by customer" → AR Summary; "Top 10 expenses" → P&L sorted; "Related party transactions" → tag during the year, not at audit time; "Variance explanation" → month-by-month P&L.
 
-**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
+## Cross-references back to engagements
 
-**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
+- `practice/references/annual-statutory.md` step 5 — audit-prep is the bridge between `year-end-close` and `statutory-filing` engagement steps. Practice playbook orchestrates audit-prep deliverables into the Form C-S wizard.
+- `practice/references/quarterly-gst.md` — keeps per-quarter F5 reconciliations clean; audit-prep step 9 trusts those.
+- `practice/references/onboarding.md` — only relevant when conversion happened mid-FY (rare). Then the audit pack must include a "conversion period" note explaining the mid-FY data load.