jaz-clio 5.1.8 → 5.2.1

package/README.md

@@ -43,15 +43,18 @@ clio calc lease --payment 5000 --term 36 --rate 5 # IFRS 16 (offline, instant)
 clio jobs month-end --period 2026-03              # Step-by-step close playbook
 clio magic create --file receipt.pdf              # AI extracts → draft transaction
 clio invoices search --query 'status:unpaid AND $500+'  # Structured per-entity search
+clio practice init --firm-name "My Firm"          # Set up a client workspace at ~/Documents/Jaz Practice
+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
 ```
 
-53 command groups. 16 report types. 13 calculators. 12 job playbooks. Every command supports `--json`. Run `clio --help` for the full list.
+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.
 
 ---
 
 ## MCP Server
 
-266 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports.
+272 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports. Includes the v5.2.0 `practice_*` tools (init, onboard_client, list_clients, load_client, create_engagement, load_engagement) so an agent in Claude Desktop or Claude Code can scaffold and load client workspaces conversationally.
 
 **Claude Code:**
 ```bash

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.1.8
+version: 5.2.1
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 117 production gotchas, error
@@ -10,7 +10,7 @@ description: >-
   schedulers, subscriptions, attachments, and Jaz Magic extraction. Also use
   when building API clients, seeding test data, or adding new endpoint support.
 license: MIT
-compatibility: Requires Jaz API key (x-jk-api-key header). Works with Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, and any agent that reads markdown.
+compatibility: Requires Jaz API key (x-jk-api-key header). Works with Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, and any agent that reads markdown. For end-to-end practitioner flows that combine these API gotchas with client + engagement context, load the jaz-practice skill (engagement-type playbooks at `jaz-practice/references/{monthly-close,quarterly-gst,annual-statutory,onboarding}.md` invoke these endpoints with concrete CLIENT.md-driven inputs).
 ---
 
 # Jaz API Skill
@@ -27,6 +27,12 @@ Before touching this skill's HTTP details, check what's actually available:
 
 The rest of this skill — field names, gotchas, error catalog, dependency order, search filter syntax — applies regardless of invocation path. Read it for *context*, not for HTTP-call construction unless you're in the third bucket.
 
+## Reading Order — Practitioner vs Integrator
+
+**Practitioner (Claude Desktop / `jaz-practice`)** — priority + engagement type typically hit during (rule numbering preserved; this is a curation overlay): (1) Identifiers & Dates 1–3 — every engagement; (2) Names & Fields 9–13 — monthly-close review; (3) Transaction Creation 14–16 — onboarding opening entries + monthly-close draft finalization; (4) Chart of Accounts 17–22 — onboarding COA setup + monthly-close classification; (5) Payments / Cross-Currency 4–8 — monthly-close payment-run + quarterly-gst AR/AP recon; (6) Journals & Cash 23–26 — monthly-close accruals + annual-statutory year-end true-ups; (7) Credit Notes & Refunds 27–28 — monthly-close AR review + ad-hoc credit issuance; (8) Reports 36–37 — every engagement, TB/BS at start of monthly-close, quarterly-gst, annual-statutory; (9) Tax Profile Scoping 100 — quarterly-gst F5 box mapping; (10) Transaction References 104 — monthly-close period-end + onboarding ref reuse; (11) Draft Finalization Pipeline 81–88 — monthly-close draft queues + onboarding draft promotion; (12) Jaz Magic / PDF-JPG 57–63 — onboarding doc capture + monthly-close document-collection; (13) Currency Rates 39, 49, 105 — monthly-close FX reval + annual-statutory year-end revaluation; (14) Withholding Tax 45, 98 — quarterly-gst + annual-statutory tax computation.
+
+**Integrator (API clients, pipelines, batch jobs, MCP/CLI)** — after the practitioner list: Bulk Upsert (Items/Contacts/Rates); Background Jobs (filter `resourceId` not `jobId`); Export Records; Pagination (38); Search & Filter (50–56); Response Shape Gotchas (66–73); Cash Entry Response Shape (74–77); Entity Resolution (78–80); Bank Rules (89–90c); Fixed Assets (91–92c); Subscriptions & Scheduled (93–94); niche endpoints (95–102); Journals balance (103); Quick Fix (107, 111); TTB (108 — onboarding-relevant); Dynamic Strings (109–110); Sub-Resource Shapes (112); Nano-Classifier (113); Scheduler Asymmetry (114); Payment Record CRUD (115–117); Bulk Upserts transactions (118–122); Reconciliation write-side (123–127); Drafts lifecycle (128–135).
+
 ## When to Use This Skill
 
 - Writing or modifying any code that calls the Jaz API
@@ -478,3 +484,4 @@ Supports `--json` for structured output. 186 articles across 20 sections. Automa
 - **jaz-jobs** — 12 accounting job playbooks (month-end close, bank recon, GST/VAT filing, etc.)
 - **jaz-conversion** — Data migration workflows from Xero, QuickBooks, Sage, MYOB, and Excel
 - **jaz-cli** — CLI command reference, auth, output formats, pagination, and workflow patterns
+- **jaz-practice** — Practitioner workspace + engagement-type wrapper (CLIENT.md, ENGAGEMENT.md, monthly-close / quarterly-gst / annual-statutory / onboarding playbooks); loads the gotchas above with concrete CLIENT.md-driven inputs (COA, materiality, JAZ_API_KEY override).

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.1.8
+version: 5.2.1
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -14,6 +14,8 @@ compatibility: Requires Node.js >= 18.0.0. Install via npm install -g jaz-clio.
 
 # Clio CLI Skill
 
+> **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).
 
 ## When to Use This Skill
@@ -35,8 +37,9 @@ You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting pl
 | 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** |
+| Client + engagement workspace (CLIENT.md, ENGAGEMENT.md, engagement types) | **jaz-practice** |
 
-Use **jaz-cli** when running commands. Use **jaz-api** when debugging API errors or understanding field mappings.
+Use **jaz-cli** when running commands. Use **jaz-api** when debugging API errors or understanding field mappings. Practice scaffolding tools (`practice_init`, `practice_onboard_client`, `practice_list_clients`, `practice_load_client`, `practice_create_engagement`, `practice_load_engagement`) live in the MCP server, not the CLI — they are invoked from inside Claude Desktop / Cowork rather than from the terminal.
 
 ## Auth Precedence
 
@@ -364,3 +367,4 @@ See [references/agent-gotchas.md](./references/agent-gotchas.md) for the full li
 - **jaz-recipes** — 16 IFRS-compliant transaction recipes with calculators and capsules
 - **jaz-jobs** — 12 accounting job playbooks (month-end close, bank recon, GST/VAT filing, etc.)
 - **jaz-conversion** — Data migration workflows from Xero, QuickBooks, Sage, MYOB, and Excel
+- **jaz-practice** — Practitioner workspace + engagement-type wrapper (CLIENT.md, ENGAGEMENT.md, onboarding / monthly-close / quarterly-gst / annual-statutory). Practice tools (`practice_init`, `practice_onboard_client`, etc.) live in the MCP surface, not the CLI.

package/assets/skills/conversion/SKILL.md

@@ -1,13 +1,16 @@
 ---
 name: jaz-conversion
-version: 5.1.8
+version: 5.2.1
 description: >-
   Use this skill when migrating accounting data into Jaz — importing from Xero,
   QuickBooks, Sage, MYOB, or Excel exports. Covers the full conversion pipeline:
   analyzing source files, mapping Chart of Accounts, contacts, tax profiles, and
   items, creating clearing accounts, running TTB (trial transaction balance),
   and verifying TB. Also use when the user mentions data migration, conversion,
-  import, or switching accounting software.
+  import, or switching accounting software. Triggered during the jaz-practice
+  onboarding flow whenever a new client's prior firm uses Xero, QuickBooks,
+  Sage, or MYOB — see `jaz-practice/references/onboarding.md` for the
+  client-folder-aware wrapper that invokes this skill.
 ---
 
 # Jaz Conversion Skill
@@ -16,6 +19,8 @@ You are performing an **accounting data conversion** — migrating a customer's
 
 **This skill provides 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.
+
 ## Guided in-app data transfer
 
 Jaz also has a guided **Data Transfer** flow available in Settings (Xero, QuickBooks, Sage, MYOB).
@@ -157,3 +162,4 @@ If TB doesn't match, identify the discrepancy:
 - **jaz-api** — Field names, endpoints, error codes, and gotchas (load alongside this skill)
 - **jaz-recipes** — Transaction recipes for complex IFRS scenarios encountered during conversion
 - **jaz-jobs** — Post-conversion operational workflows (month-end close, bank recon, etc.)
+- **jaz-practice** — Client-folder + engagement wrapper. The onboarding flow (`practice_onboard_client` + `jaz-practice/references/onboarding.md`) is the typical entry point for invoking this skill: it captures CLIENT.md basics, scaffolds the client folder, and routes to this skill for the data move. After verification passes, the recurring engagement cadence (monthly-close / quarterly-gst / annual-statutory) begins.

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.1.8
+version: 5.2.1
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,
@@ -9,7 +9,7 @@ description: >-
   when the user mentions closing the books, period-end, tax filing, or any
   operational accounting task.
 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 jaz-recipes skill.
+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 jaz-recipes skill. For the engagement-type wrapper that invokes these blueprints inside a client workspace, load the jaz-practice skill (see `jaz-practice/references/<engagement-type>.md` for canonical engagement-type definitions).
 ---
 
 # Jobs Skill
@@ -38,23 +38,23 @@ Period-close jobs build on each other. Quarter = month + extras. Year = quarter
 
 | Job | CLI Command | Description |
 |-----|-------------|-------------|
-| **Month-End Close** | `clio jobs month-end --period YYYY-MM` | 5 phases: pre-close prep, accruals, valuations, verification, lock. The foundation. |
-| **Quarter-End Close** | `clio jobs quarter-end --period YYYY-QN` | Month-end for each month + GST/VAT, ECL review, bonus accruals, intercompany, provisions. |
-| **Year-End Close** | `clio jobs year-end --period YYYY` | Quarter-end for each quarter + true-ups, dividends, CYE rollover, audit prep, final lock. |
+| **Month-End Close** (`generate_month_end_blueprint`) | `clio jobs month-end --period YYYY-MM` | 5 phases: pre-close prep, accruals, valuations, verification, lock. The foundation. *Used in: monthly-close engagement (see `jaz-practice/references/monthly-close.md`).* |
+| **Quarter-End Close** (`generate_quarter_end_blueprint`) | `clio jobs quarter-end --period YYYY-QN` | Month-end for each month + GST/VAT, ECL review, bonus accruals, intercompany, provisions. *Used in: monthly-close engagement (3-month roll-up at quarter boundary; see `jaz-practice/references/monthly-close.md`).* |
+| **Year-End Close** (`generate_year_end_blueprint`) | `clio jobs year-end --period YYYY` | Quarter-end for each quarter + true-ups, dividends, CYE rollover, audit prep, final lock. *Used in: annual-statutory engagement (see `jaz-practice/references/annual-statutory.md`).* |
 
 ### Ad-Hoc Jobs
 
 | Job | CLI Command | Description |
 |-----|-------------|-------------|
-| **Bank Recon** | `clio jobs bank-recon` | Clear unreconciled items: match, categorize, resolve. Paired tool: `clio jobs bank-recon match`. |
-| **Document Collection** | `clio jobs document-collection` | Scan and classify client documents from local directories and cloud links (Dropbox, Drive, OneDrive). Outputs file paths for agent upload. Paired tool: `clio jobs document-collection ingest`. |
-| **GST/VAT Filing** | `clio jobs gst-vat --period YYYY-QN` | Tax ledger review, discrepancy check, filing summary. |
-| **Payment Run** | `clio jobs payment-run` | Select outstanding bills by due date, process payments. |
-| **Credit Control** | `clio jobs credit-control` | AR aging review, overdue chase list, bad debt assessment. |
-| **Supplier Recon** | `clio jobs supplier-recon` | AP vs supplier statement, identify mismatches. |
-| **Audit Preparation** | `clio jobs audit-prep --period YYYY` | Compile reports, schedules, reconciliations for auditor/tax. |
-| **FA Review** | `clio jobs fa-review` | Fixed asset register review, disposal/write-off processing. |
-| **Statutory Filing** | `clio jobs statutory-filing` | Corporate income tax computation and filing. Paired tools: `clio jobs statutory-filing sg-cs`, `clio jobs statutory-filing sg-ca`. |
+| **Bank Recon** (`generate_bank_recon_blueprint`) | `clio jobs bank-recon` | Clear unreconciled items: match, categorize, resolve. Paired tool: `clio jobs bank-recon match`. *Used in: monthly-close engagement (run as part of every period close; see `jaz-practice/references/monthly-close.md`).* |
+| **Document Collection** (`generate_document_collection_blueprint`) | `clio jobs document-collection` | Scan and classify client documents from local directories and cloud links (Dropbox, Drive, OneDrive). Outputs file paths for agent upload. Paired tool: `clio jobs document-collection ingest`. *Used in: onboarding flow (initial client doc capture; see `jaz-practice/references/onboarding.md`) and the open phase of every engagement (monthly-close, quarterly-gst, annual-statutory).* |
+| **GST/VAT Filing** (`generate_gst_vat_blueprint`) | `clio jobs gst-vat --period YYYY-QN` | Tax ledger review, discrepancy check, filing summary. *Used in: quarterly-gst engagement (see `jaz-practice/references/quarterly-gst.md`).* |
+| **Payment Run** (`generate_payment_run_blueprint`) | `clio jobs payment-run` | Select outstanding bills by due date, process payments. *Used in: monthly-close engagement (AP cycle inside the period close; see `jaz-practice/references/monthly-close.md`).* |
+| **Credit Control** (`generate_credit_control_blueprint`) | `clio jobs credit-control` | AR aging review, overdue chase list, bad debt assessment. *Used in: ad-hoc engagement (run on-demand when AR aging deteriorates; not tied to a recurring engagement type).* |
+| **Supplier Recon** (`generate_supplier_recon_blueprint`) | `clio jobs supplier-recon` | AP vs supplier statement, identify mismatches. *Used in: annual-statutory engagement (audit AP confirmations; see `jaz-practice/references/annual-statutory.md`) and ad-hoc engagement (when statement mismatches surface mid-period).* |
+| **Audit Preparation** (`generate_audit_prep_blueprint`) | `clio jobs audit-prep --period YYYY` | Compile reports, schedules, reconciliations for auditor/tax. *Used in: annual-statutory engagement (see `jaz-practice/references/annual-statutory.md`).* |
+| **FA Review** (`generate_fa_review_blueprint`) | `clio jobs fa-review` | Fixed asset register review, disposal/write-off processing. *Used in: annual-statutory engagement (asset register sign-off as part of year-end; see `jaz-practice/references/annual-statutory.md`).* |
+| **Statutory Filing** (`generate_statutory_filing_blueprint`) | `clio jobs statutory-filing` | Corporate income tax computation and filing. Paired tools: `clio jobs statutory-filing sg-cs`, `clio jobs statutory-filing sg-ca`. *Used in: annual-statutory engagement (see `jaz-practice/references/annual-statutory.md`).* |
 
 ## How Jobs Work
 
@@ -95,8 +95,9 @@ clio jobs fa-review [--json]
 | **jaz-api** | Provides the exact API payloads for each step (field names, gotchas, error handling) |
 | **jaz-recipes** | Provides the accounting patterns for complex steps (accruals, FX reval, ECL, etc.) |
 | **jaz-jobs** (this skill) | Combines recipes + API into sequenced, verifiable business processes |
+| **jaz-practice** | Wraps these blueprints inside the practitioner's client + engagement context. The 12 blueprints map to engagement types: month-end / quarter-end / bank-recon / payment-run → monthly-close; gst-vat → quarterly-gst; year-end / audit-prep / fa-review / supplier-recon / statutory-filing → annual-statutory; document-collection → onboarding flow + every engagement open phase; credit-control → ad-hoc. |
 
-**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.
+**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. When invoked from inside a client folder, jaz-practice supplies the CLIENT.md context (COA, materiality, JAZ_API_KEY override) that these blueprints consume.
 
 ## Supporting Files
 

package/assets/skills/practice/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: jaz-practice
+version: 5.2.1
+description: >-
+  Use this skill whenever an accounting practitioner is doing client work in
+  Jaz — closing the books, filing GST, year-end statutory, onboarding a new
+  client. Covers the practitioner workspace at ~/Documents/Jaz Practice
+  (clients/<slug>/CLIENT.md and engagements/<slug>/ENGAGEMENT.md), engagement
+  routing (monthly-close | quarterly-gst | annual-statutory | onboarding |
+  adhoc), and how the agent loads client context before invoking jaz-jobs
+  blueprints, jaz-recipes recipes, and jaz-api tools. Triggers on intent like
+  "close the books for X", "file GST for Y", "onboard new client Z", "what's
+  outstanding for Acme this month". Pair with jaz-jobs (workflow blueprints),
+  jaz-recipes (IFRS recipes + calculators), jaz-api (REST gotchas), and
+  jaz-conversion (data migration during onboarding).
+compatibility:
+  jaz-jobs: ">=5.1"
+  jaz-recipes: ">=5.1"
+  jaz-api: ">=5.1"
+  jaz-conversion: ">=5.1"
+  jaz-cli: ">=5.1"
+---
+
+# jaz-practice
+
+Practitioner-side scaffolding. The agent's entry point when an accountant is doing client work in Jaz.
+
+## Mental model
+
+| Engineer (cct-toolkit) | Practitioner (jaz-practice) |
+|-------------------------|------------------------------|
+| Workspace = a feature being built | Workspace = a client being served |
+| Sub-folder = task category | Sub-folder = engagement type (recurring/special) |
+| FEATURE.md hub | CLIENT.md (master) + ENGAGEMENT.md (per-engagement) |
+| Decisions = architecture | Decisions = accounting treatment (estimate, classification, scope) |
+| Done = PR merged | Done = engagement signed-off, period locked, deliverable filed |
+
+The persistent unit is the **client**, not the project. Engineering features come and go; clients accumulate over years. The folder structure must support: historical immutability (last year's audit file is sacred), recurring rhythm (monthly close, quarterly GST), ad-hoc work (M&A, restructuring), and cross-engagement context (the same client's tax position informs their audit risk).
+
+## Folder layout
+
+```
+~/Documents/Jaz Practice/        ← override with PRACTICE_HOME env or --root
+  PRACTICE.md                    ← firm-level config (one-time)
+  templates/                     ← practitioner-overridable copies of engagement templates
+  clients/<client-slug>/
+    CLIENT.md                    ← master file: legal entity, FY, GST, COA, banks, recurring accruals, materiality
+    engagements/<engagement-slug>/
+      ENGAGEMENT.md              ← per-engagement: type, period, status, scope, queries, decisions, journal
+      inputs/                    ← raw client docs (statements, invoices, receipts)
+      workpapers/                ← TBs, analyses, sample selections
+      deliverables/              ← signed reports, filed returns, board packs
+    recurring/{monthly,quarterly,annual}/<period>/   ← close packages, GST returns, statutory
+    correspondence/                                  ← IRAS letters, ACRA notices
+    _archive/                                        ← closed engagements, prior periods
+```
+
+See `references/client-md-schema.md` and `references/engagement-md-schema.md` for the full field-by-field schema.
+
+## Engagement-type routing (the agent's first move)
+
+When the practitioner expresses intent, route to the right engagement type and load the matching deep reference:
+
+| Practitioner says... | Engagement type | Deep reference | Driver tools |
+|----------------------|-----------------|----------------|---------------|
+| "Close the books for <client> <month>" | `monthly-close` | `references/monthly-close.md` | `generate_month_end_blueprint` + accrual / depreciation / fx-reval recipes |
+| "File GST/F5 for <client> <quarter>" | `quarterly-gst` | `references/quarterly-gst.md` | `generate_gst_vat_blueprint` + `generate_vat_ledger` |
+| "Year-end / annual / statutory for <client>" | `annual-statutory` | `references/annual-statutory.md` | `generate_year_end_blueprint` + `generate_audit_prep_blueprint` + `generate_statutory_filing_blueprint` |
+| "Onboard <new client>" / "Take over from <prior firm>" | `onboarding` | `references/onboarding.md` | `practice_onboard_client` + `jaz-conversion` if migrating |
+| Anything else | `adhoc` | (no reference) | Whatever the practitioner names |
+
+## How the agent works inside jaz-practice
+
+1. **Detect the practitioner workspace.** If `~/Documents/Jaz Practice/` exists (or `PRACTICE_HOME` is set), call `practice_list_clients` first to surface the available client slugs. If the practitioner's intent names a client, slug it and call `practice_load_client`.
+2. **One key per session.** v5.2.0 uses a single `JAZ_API_KEY` per Claude session (set once in connector / settings / env). The `CLIENT.md.jaz_api_key_override` field is reserved for v5.3 multi-org runtime selection — not yet wired. Don't prompt the practitioner to re-enter a key per client. For multi-org agencies today: use one Jaz org per Claude session and switch sessions when switching orgs.
+3. **Anchor work in an engagement.** Either find the active engagement for the period (in `practice_load_client`'s response) or create one with `practice_create_engagement(clientSlug, type, period)`. The engagement folder gets the type-specific template.
+4. **Follow the deep reference.** Load `references/<type>.md` for the canonical playbook — it names every tool / recipe / calculator and every CLIENT.md / ENGAGEMENT.md field.
+5. **Surface, don't dump.** When invoking blueprints or running reports, surface to the practitioner: top 3 exceptions, top 3 unreconciled items, top 3 unresolved queries. Save full output to `workpapers/<task>.md`.
+6. **Append progress to ENGAGEMENT.md daily journal** so resuming the next session doesn't redo yesterday's work.
+7. **Transition status only when the scope checklist is complete.** Don't mark `signed-off` / `filed` / `archived` while items remain unticked.
+
+## Key principle: jaz-practice routes, it does NOT duplicate
+
+The 6 `practice_*` MCP tools and the CLI command group are **filesystem scaffolding only**. They never call the Jaz API. All real accounting work goes through:
+- **jaz-jobs** for workflow blueprints (12 playbooks)
+- **jaz-recipes** for IFRS-compliant transaction modeling (16 recipes + 13 calculators)
+- **jaz-api** for direct REST API operations (266 tools, error/field gotchas)
+- **jaz-conversion** for data migration during onboarding
+- **jaz-cli** for terminal-first power users (script automation)
+
+If you find yourself wanting a new "do this accounting work" tool inside jaz-practice, stop — extend the existing skill instead, and add a cross-reference here.
+
+## Out of scope
+
+This skill is intentionally focused on accounting workflows. Out of scope:
+- KYC / AML / beneficial ownership (firm administration, not accounting work)
+- Engagement letters, fee structures, billing rates
+- Sign-off log mechanics, partner-review thresholds
+- Practice management overhead (CRM, time tracking, invoicing the firm's clients for fees)
+
+## Related
+
+- `jaz-jobs/SKILL.md` — 12 workflow blueprints (cross-referenced from each engagement-type playbook)
+- `jaz-recipes/SKILL.md` — 16 IFRS recipes + 13 calculators
+- `jaz-api/SKILL.md` — REST API gotchas
+- `jaz-conversion/SKILL.md` — Xero/QB/Sage/MYOB migration playbook
+- `jaz-cli/SKILL.md` — terminal automation reference
+- `references/monthly-close.md` — canonical monthly-close playbook
+- `references/quarterly-gst.md` — canonical GST/F5 playbook
+- `references/annual-statutory.md` — canonical year-end playbook
+- `references/onboarding.md` — canonical new-client playbook
+- `references/client-md-schema.md` — every CLIENT.md field
+- `references/engagement-md-schema.md` — every ENGAGEMENT.md field
+- `references/troubleshooting.md` — common error classes + recovery actions

package/assets/skills/practice/references/annual-statutory.md

@@ -0,0 +1,256 @@
+# Annual statutory — agent playbook
+
+Canonical playbook the agent walks through when the practitioner says "year-end `<FY>` for `<client>`" and an active engagement of `type: annual-statutory` is loaded. Three driver tools run in sequence: `generate_year_end_blueprint` → `generate_audit_prep_blueprint` → `generate_statutory_filing_blueprint`. Driver context: `CLIENT.md` + `ENGAGEMENT.md`.
+
+## Tools, recipes, calculators this engagement uses
+
+### Tools (jaz-api / direct API)
+- `generate_year_end_blueprint` — used in step 2: drives the year-end close (true-ups, dividends, CYE rollover, final lock).
+- `generate_audit_prep_blueprint` — used in step 5: drives audit-pack assembly.
+- `generate_statutory_filing_blueprint` — used in step 7: drives the corporate-tax / Form C-S workstream.
+- `generate_trial_balance` — used in steps 1, 3, 6, 9: open TB, post-true-ups TB, audit-pack TB, final filed TB.
+- `generate_balance_sheet` / `generate_profit_and_loss` — used in step 6: deliverable reports.
+- `generate_cashflow` — used in step 6: cashflow statement.
+- `generate_equity_movement` — used in step 6: statement of changes in equity.
+- `generate_aged_ar` / `generate_aged_ap` — used in step 4 (ECL true-up) and step 5 (audit confirmations).
+- `generate_fa_summary` — used in step 4: FA register year-end snapshot, ties to BS Fixed Assets line.
+- `generate_fa_recon_summary` — used in step 4: rolls FA cost + accumulated depreciation movement.
+- `generate_general_ledger` — used in step 5: lead-schedule ties for material accounts.
+- `generate_ar_report` / `generate_supplier_recon_blueprint` — used in step 5: AR/AP confirmation lists.
+- `search_fixed_assets` — used in step 4: pull all assets to identify disposals not yet posted.
+- `search_capsules` — used in step 4: enumerate active provisions, leases, intercompany capsules requiring year-end attention.
+- `list_currency_rates` — used in step 4 FX reval: fetch FY-end closing rates per pair.
+- `bulk_finalize_drafts` — used after each recipe step (3, 4, 8): batch finalize.
+- `validate_journal_draft` — used before any `bulk_finalize_drafts`.
+- `update_account` — used in step 9: lock dates per account at FY-end.
+- `export_records` / `download_export` — used in step 5: deliverable XLSX exports for auditor pack.
+
+### Recipes (jaz-recipes)
+- `plan_recipe(name: 'depreciation', …)` — used in step 4: annual depreciation true-up for non-SL assets.
+- `plan_recipe(name: 'fx-reval', …)` — used in step 4: year-end revaluation per non-base-currency monetary balance (jaz-recipes "annual-statutory" engagement context).
+- `plan_recipe(name: 'asset-disposal', …)` — used in step 4: disposals surfaced during FA review.
+- `plan_recipe(name: 'ecl', …)` — used in step 4: IFRS 9 year-end true-up over `generate_aged_ar`.
+- `plan_recipe(name: 'provision', …)` — used in step 4: IAS 37 remeasurement.
+- `plan_recipe(name: 'dividend', …)` — used in step 8: declaration after profit finalization (per jaz-recipes annual-statutory context).
+
+### Calculators (jaz-cli)
+- `clio calc loan` — used in step 4: independent verification of loan schedules at FY-end.
+- `clio calc lease` — used in step 4: IFRS 16 ROU register + liability unwinding cross-check.
+- `clio calc provision` — used in step 4: PV unwinding cross-check.
+- `clio calc asset-disposal` — used in step 4: gain/loss verification before invoking the recipe.
+- `clio calc fx-reval` — used in step 4: year-end FX delta cross-check.
+- `clio calc ecl` — used in step 4: provision matrix cross-check.
+- `clio calc dividend` — used in step 8: with optional withholding-rate.
+- `clio jobs statutory-filing sg-cs` — used in step 7: Form C-S deterministic computation engine (input: structured JSON; output: workpaper + Form C-S fields + carry-forwards).
+- `clio jobs statutory-filing sg-ca` — used in step 7: capital-allowance schedule per asset category.
+
+### Cross-references
+- `jaz-jobs/SKILL.md § generate_year_end_blueprint`, `§ generate_audit_prep_blueprint`, `§ generate_statutory_filing_blueprint` for blueprint structure.
+- `jaz-jobs/references/year-end-close.md`, `audit-prep.md`, `fa-review.md`, `supplier-recon.md` for blueprint depth.
+- `jaz-jobs/references/sg-tax/wizard-workflow.md` for the Form C-S wizard procedure (THE main playbook for step 7); `sg-tax/{form-cs-fields,data-extraction,add-backs-guide,capital-allowances-guide,ifrs16-tax-adjustment,enhanced-deductions,exemptions-and-rebates,losses-and-carry-forwards}.md` for tax-rule depth.
+- `jaz-recipes/references/{asset-disposal,fx-revaluation,provisions,bad-debt-provision,dividend,intercompany,capital-wip,ifrs16-lease,declining-balance}.md` for IFRS treatment depth.
+- `jaz-api/SKILL.md § Reports` (rules 36–37), `§ Currency Rates` (39, 49, 105), `§ Withholding Tax` (45, 98), `§ Identifiers & Dates` (1–3), `§ Pagination` (38).
+
+---
+
+## Step-by-step playbook
+
+### Step 1 — Pre-flight + frame the FY
+
+Read `CLIENT.fy_end` (MM-DD) and `ENGAGEMENT.period` (YYYY). Compute the FY window:
+- FY-start = (year-1)-`fy_end` + 1 day if `fy_end == 12-31` else `period`-`fy_end_month_start`
+- FY-end = `period`-`fy_end`
+
+Verify all 12 monthly closes (or 4 quarter-end closes if the firm operates on a quarterly cadence) are signed-off OR the period is locked. Surface any gaps; halt unless practitioner authorises.
+
+Invoke `generate_trial_balance(period_end: <FY-end>)`. Save to `recurring/annual/<period>/audit/tb-pre-yearend.json`.
+
+### Step 2 — Year-end blueprint
+
+Invoke `generate_year_end_blueprint(period: <ENGAGEMENT.period>, currency: <CLIENT.base_currency>)`. Save to `recurring/annual/<period>/year-end-blueprint.json`.
+
+The blueprint emits phased steps for: monthly true-ups + bonus accrual true-up + annual ECL + year-end FX reval + dividend (if applicable) + final lock. The playbook below maps the blueprint phases onto concrete tool/recipe invocations.
+
+**On 422 with `prior_year_not_locked`:** the prior FY was not closed. Halt: "Prior FY `<period - 1>` not locked — close prior FY before starting current year-end."
+
+### Step 3 — Pull the opening register set
+
+Save the following to `recurring/annual/<period>/audit/`:
+
+- `search_fixed_assets(filter: {status: {in: ['ACTIVE', 'DISPOSED']}}, valueDateRange: { from: <FY-start>, to: <FY-end> }, limit: 200)` paginated → `fa-register.json`
+- `search_capsules(filter: {status: {in: ['ACTIVE', 'CLOSED']}, tag: {in: ['lease', 'loan', 'provision', 'intercompany', 'capital-wip']}}, limit: 200)` paginated → `capsules.json`
+- `generate_aged_ar(period_end: <FY-end>)` → `aged-ar.json`
+- `generate_aged_ap(period_end: <FY-end>)` → `aged-ap.json`
+
+### Step 4 — Year-end recipes (true-ups, FX reval, ECL, provisions, FA disposals)
+
+This is the largest step and runs through the recipe set in this order:
+
+#### 4a — Depreciation annual true-up
+
+Invoke `generate_fa_summary(period_end: <FY-end>)`. For every active asset:
+- If `depreciationMethod == STRAIGHT_LINE`: Jaz native FA already posted monthly. Verify the year's accumulated depreciation per the report. Cross-check via `clio calc depreciation --cost <c> --salvage <s> --life <l> --method sl --frequency annual --currency <CLIENT.base_currency> --json`. Tolerance: `CLIENT.materiality_threshold`.
+- If `depreciationMethod ∈ { DDB, 150DB }`: confirm the 12 monthly close engagements posted via `plan_recipe(name: 'depreciation', …)`. Year-end true-up only if a remeasurement of `usefulLife` happened during FY.
+
+#### 4b — FA disposals discovered during review
+
+For each asset where `search_fixed_assets` returns `status: DISPOSED` but no asset-disposal capsule exists, OR the practitioner identifies a missed disposal during review:
+1. `clio calc asset-disposal --cost <c> --salvage <s> --life <l> --acquired <YYYY-MM-DD> --disposed <YYYY-MM-DD> --proceeds <p> --method <sl|ddb|150db> --currency <CLIENT.base_currency> --json` for verification.
+2. `plan_recipe(name: 'asset-disposal', cost: <c>, accumulated: <accumulated-to-disposal-date>, disposalDate: <YYYY-MM-DD>, proceeds: <p>, glAccountCost: <FA gl>, glAccountAccumulated: <accumulated gl>, glAccountGainLoss: <P&L line>, …)`.
+3. `execute_recipe`. Inspect `notes` — typically includes a `note` action to deregister the asset in the FA module.
+
+**On 422 from `plan_recipe` with `disposal_after_period_end`:** the disposal date is later than `<FY-end>`. The disposal belongs to next FY; halt and confirm with practitioner.
+
+#### 4c — Year-end FX revaluation
+
+Same logic as monthly-close step 6, but at `<FY-end>` and with the FY closing rates. Pull rates: `list_currency_rates(filter: {sourceCurrency: <fcy>, valueDate: <FY-end>})` per non-base-currency.
+
+For each foreign-currency monetary balance:
+1. `clio calc fx-reval --amount <fcy> --book-rate <booked> --closing-rate <fy-close> --currency <fcy> --base-currency <CLIENT.base_currency> --json`.
+2. `plan_recipe(name: 'fx-reval', …)` then `execute_recipe`.
+
+The Day-1 reversal scheduler will post on FY-start of the next FY automatically.
+
+**On 404 from `list_currency_rates`:** FY-end rate not loaded. `bulk_upsert_currency_rates` to load rates for all required pairs before proceeding (jaz-api rule 39 — auto-enables currencies not yet enabled).
+
+#### 4d — IFRS 9 ECL year-end true-up
+
+1. `generate_aged_ar(period_end: <FY-end>)`.
+2. Bucket receivables by aging band per CLIENT historical loss-rate matrix.
+3. `clio calc ecl --current <c> --30d <30> --60d <60> --90d <90> --120d <120> --rates <r1>,<r2>,<r3>,<r4>,<r5> --existing-provision <ep> --currency <CLIENT.base_currency> --json`.
+4. If top-up > `CLIENT.materiality_threshold`: `plan_recipe(name: 'ecl', …)` then `execute_recipe`.
+
+#### 4e — IAS 37 provisions remeasurement
+
+For each capsule from step 3 with `tag: 'provision'`:
+1. `clio calc provision --amount <pv> --rate <discount-rate> --term <remaining-months-to-FY-end> --currency <CLIENT.base_currency> --json` to verify cumulative discount unwinding.
+2. If best-estimate has changed materially during FY: re-run `plan_recipe(name: 'provision', …)` with new amount; the recipe creates a remeasurement journal.
+
+#### 4f — Bonus accrual true-up
+
+If `CLIENT.recurring_accruals[]` includes bonus-accrual entries with `estimation_method != fixed_amount`: pull actual final-bonus figures from the practitioner; reverse the over-/under-accrued portion via a manual `create_journal` tagged to the bonus capsule. (The leave-accrual half stays on its scheduler — no true-up needed unless leave policy changed mid-FY.)
+
+#### 4g — Intercompany elimination
+
+For each capsule with `tag: 'intercompany'`: confirm both legs (in two Jaz orgs if practitioner serves both) have matching reference numbers and equal-and-opposite balances. Surface any imbalance > `CLIENT.materiality_threshold` to practitioner.
+
+#### 4h — Capital-WIP transfers
+
+For each capsule with `tag: 'capital-wip'` whose underlying project is COMMISSIONED during FY: trigger the WIP→FA transfer per `jaz-recipes/references/capital-wip.md`. The transfer is `POST /api/v1/transfer-fixed-assets` (preserves accumulated depreciation per jaz-conversion rule 2).
+
+#### Finalize step 4
+
+Collect all draft journals from 4a–4h, run `validate_journal_draft` per draft, then `bulk_finalize_drafts({ kind: 'journal', resourceIds: [...] })`. Save a manifest to `recurring/annual/<period>/audit/year-end-recipes-manifest.md`.
+
+### Step 5 — Audit prep pack
+
+Invoke `generate_audit_prep_blueprint(period: <ENGAGEMENT.period>)`. Save the blueprint to `recurring/annual/<period>/audit/blueprint.json`.
+
+Assemble the audit pack into `deliverables/audit/`:
+- TB final, BS, P&L, cashflow, equity movement → from step 6
+- FA register snapshot (from `generate_fa_summary` + `generate_fa_recon_summary`)
+- Aged AR / AP with confirmation list (`generate_aged_ar` / `generate_aged_ap` filtered by materiality)
+- Lead schedules per material account: `generate_general_ledger(accountResourceId: <id>, period_start: <FY-start>, period_end: <FY-end>)` per material GL.
+- Supplier recon pack: `generate_supplier_recon_blueprint(period: <ENGAGEMENT.period>)` per material supplier.
+- Year-end recipes manifest from step 4 (audit trail of every adjusting journal).
+- Capsule listing from step 3.
+
+For each deliverable, invoke `export_records({ entityType: …, period: <ENGAGEMENT.period>, outputFormat: 'XLSX' })` to emit XLSX where appropriate; poll `search_background_jobs(filter: {resourceId: {eq: <jobId>}})` to `SUCCESS`; `download_export` to `deliverables/audit/`.
+
+### Step 6 — Final report set
+
+After step 4 finalizations, invoke and save to `deliverables/audit/`:
+- `generate_trial_balance(period_end: <FY-end>)` → `tb-final.json`
+- `generate_balance_sheet(period_end: <FY-end>)` → `bs.json`
+- `generate_profit_and_loss(period_start: <FY-start>, period_end: <FY-end>)` → `pl.json`
+- `generate_cashflow(period_start: <FY-start>, period_end: <FY-end>)` → `cf.json`
+- `generate_equity_movement(period_start: <FY-start>, period_end: <FY-end>)` → `equity.json`
+
+Verify ties: `tb-final.balance_sheet_total == bs.total_assets == bs.total_liabilities + bs.total_equity`. If not within rounding: halt and surface "BS/TB mismatch — investigate before signing audit pack."
+
+### Step 7 — Corporate tax (Form C-S workstream)
+
+Invoke `generate_statutory_filing_blueprint`. Save to `recurring/annual/<period>/tax/blueprint.json`.
+
+Form C-S applies if revenue ≤ SGD 5M; Form C-S Lite if revenue ≤ SGD 200K. NOT Form C (out of scope per jaz-jobs § Tax Computation).
+
+Run the wizard per `jaz-jobs/references/sg-tax/wizard-workflow.md`:
+1. Pull P&L, TB, GL, FA data per `sg-tax/data-extraction.md`.
+2. Classify add-backs per `sg-tax/add-backs-guide.md` (entertainment, motor private-passenger, fines & penalties, donations >250%, depreciation if accounting basis).
+3. Capital allowances per `sg-tax/capital-allowances-guide.md` and via `clio jobs statutory-filing sg-ca --input assets.json --json` per asset category.
+4. IFRS 16 tax adjustment per `sg-tax/ifrs16-tax-adjustment.md` — reverse depreciation + interest, add back actual lease payments.
+5. Enhanced deductions per `sg-tax/enhanced-deductions.md` (R&D, IP, donations 250%, S14Q renovation).
+6. Exemptions / rebates per `sg-tax/exemptions-and-rebates.md` and per `CLIENT.corporate_tax_bracket` (SUTE / PTE / standard / partial).
+7. Losses + carry-forwards per `sg-tax/losses-and-carry-forwards.md`.
+8. Assemble `tax-data.json` and run: `clio jobs statutory-filing sg-cs --input tax-data.json --json`.
+9. Output: workpaper + the Form C-S field set (18 fields for C-S, 6 for C-S Lite per `sg-tax/form-cs-fields.md`) + carry-forward schedule.
+
+Save outputs to `deliverables/tax/`:
+- `workpaper.json` (full computation trail)
+- `form-cs-fields.json` (the 18 / 6 IRAS fields)
+- `carry-forwards.json` (loss / CA / donation carry-forward schedule)
+
+Practitioner submits on myTax Portal manually. Capture submission reference into `deliverables/tax/iras-ack-form-cs.txt`.
+
+### Step 8 — Dividends (if applicable)
+
+If the board declares a dividend post profit-finalization (per jaz-recipes annual-statutory context):
+1. `clio calc dividend --amount <amt> --declaration-date <YYYY-MM-DD> --payment-date <YYYY-MM-DD> [--withholding-rate <r>] --currency <CLIENT.base_currency> --json`.
+2. `plan_recipe(name: 'dividend', amount: <amt>, declarationDate: <YYYY-MM-DD>, paymentDate: <YYYY-MM-DD>, withholdingRate: <r>, …)` then `execute_recipe`. Recipe creates declaration journal (reduces retained earnings) + payment journal + optional WHT journal.
+3. `bulk_finalize_drafts`.
+
+For cross-border WHT obligations: see jaz-api § Withholding Tax (rules 45, 98).
+
+### Step 9 — IRAS ECI (if not yet filed)
+
+ECI deadline: 3 months after FY-end. If ECI was filed earlier in the FY (typical practice), confirm reference is recorded in `deliverables/iras/eci-ack.txt`.
+
+If not yet filed: use the Form C-S working from step 7 to compute estimated chargeable income; submit on myTax Portal; capture reference.
+
+### Step 10 — ACRA annual return
+
+Annual return deadline: 7 months after FY-end (for non-listed; rules differ for listed entities — out of MVP scope).
+
+- AGM minutes drafted (where required by Companies Act).
+- Financial statements lodged in XBRL where applicable (small companies: simplified XBRL).
+- File AR on BizFile+; capture reference into `deliverables/acra/ar-ack.txt`.
+
+(ACRA filing happens outside Jaz's API surface. Jaz provides the financial statements; lodgment is manual.)
+
+### Step 11 — CYE rollover + final lock
+
+Per `generate_year_end_blueprint` final phase:
+1. P&L close: roll P&L net result into Retained Earnings via a CYE journal (the blueprint emits the exact entries).
+2. `bulk_finalize_drafts` for the rollover journal.
+3. Lock all accounts at `<FY-end>` via `update_account` (lock-date field).
+
+Update `ENGAGEMENT.status` to `filed` once Form C-S, ECI, and ACRA AR acknowledgements are all captured.
+
+### Step 12 — Verification gate
+
+Before declaring `filed`:
+1. `generate_trial_balance(period_end: <FY-end>)` matches BS + P&L (sums tie).
+2. P&L net result == change in retained earnings on equity-movement statement.
+3. `search_journals(status: 'DRAFT', valueDate: {lte: <FY-end>})` returns zero across all years.
+4. `search_bank_records(status: 'UNRECONCILED', valueDate: {lte: <FY-end>})` returns zero.
+5. FA register net-book-value (`generate_fa_summary`) ties to BS Fixed Assets line.
+6. Form C-S, ECI, ACRA AR acknowledgements all in `deliverables/`.
+
+If any fails: do NOT mark `filed`. Surface the failed check.
+
+---
+
+## Common error classes and recovery
+
+| Error class | Where | Recovery |
+|---|---|---|
+| 422 `prior_year_not_locked` | `generate_year_end_blueprint` | Close prior FY first; halt. |
+| 422 `disposal_after_period_end` | `plan_recipe(name: 'asset-disposal', …)` | Disposal date > FY-end; belongs to next FY. |
+| 422 `journal_unbalanced` | `bulk_finalize_drafts` | Recipe regression; halt without retry. |
+| 404 `currency_rate_missing` | step 4c FX reval | `bulk_upsert_currency_rates` to load FY-end rates; auto-enables currencies (jaz-api rule 39). |
+| 422 `account_locked` | step 4 recipe execution | A monthly close already locked the account; lift lock for that specific account, post adjustment, re-lock. |
+| 500 transient | `generate_*` reports / blueprints | Retry once with 5s backoff; second 500 → halt with `requestId`. |
+| Tax-data validation error | `clio jobs statutory-filing sg-cs` | Inspect the wizard output — typically a missing field; fix `tax-data.json` per `sg-tax/form-cs-fields.md`. |
+| BS ≠ TB at step 6 | verification | Investigate before signing; do NOT proceed to filing. |
+
+(Field-name and error-recovery depth lives in `jaz-api/SKILL.md`. This file enumerates only what annual-statutory specifically encounters.)