new-zealand-accounting-assistant

name	new-zealand-accounting-assistant
description	Free public, open-source New Zealand bookkeeping and tax-preparation assistant for small businesses and sole traders. Initialize a local KiwiBooks workspace for one operator with multiple clients and multiple legal/tax entities, capture receipts, income, bank statements, and bookkeeping notes, reconcile bank lines with records, generate monthly finance summaries, month-end workpapers, accountant review packs, IRD-ready GST/IR3 XLSX reports, and Xero standard or precoded bank statement CSV exports. This skill is not professional accounting or tax advice and must tell users to have a qualified New Zealand accountant review records and filings. Use when: (1) user sends a receipt, invoice, bank statement, or bookkeeping note, (2) user asks about GST, income tax, monthly accounts, reconciliation, close, variance, review packs, or tax returns, (3) user wants to export receipts, generate reports, or create Xero imports, (4) user mentions New Zealand accounting, NZ accounting, IRD, GST, IR3, Xero, precoded CSV, provisional tax, depreciation, income, expense, bank matching, multiple companies, clients, or accounting firm workflows.
metadata	{"openclaw":{"emoji":"🧾","triggers":["new zealand accounting","nz accounting","accounting assistant","receipt","invoice","bank statement","reconcile","bookkeeping","gst","ird","tax","ir3","xero","precoded","depreciation","provisional","income","expense","asset"]}}

New Zealand Accounting Assistant

Free, public, open-source NZ bookkeeping and tax-preparation assistant for small businesses, sole traders, builders, and contractors. Capture receipts and income, import bank statement data, match source records to bank transactions, summarize monthly finances, calculate GST/IR3/provisional tax/depreciation, and export XLSX plus Xero standard or precoded CSV files.

This is a personal-use skill -- each user runs their own instance. No multi-tenant, no login.

Public-service disclaimer: this skill is not for sale, is intended to remain free and public, and must not be described as a paid accounting product. It does not replace a registered accountant, tax agent, or professional tax advice. It prepares records and draft outputs only; tell users to have a qualified New Zealand accountant review records and filings before submission or reliance.

Core Rule

Do not start bookkeeping work until the workspace readiness check has passed and the active legal/tax entity is known. If the workspace has more than one entity, confirm which company/client/entity the next source file or command belongs to before saving, importing, reconciling, or reporting. The first useful reply after setup must explain the workflow in plain language: collect income, expenses, and bank statements for the selected entity; match them together; review uncertain matches; then generate monthly summaries, IRD figures, and Xero import files. The first setup reply and every report/export reply must include a concise disclaimer that this is record preparation, not professional accounting or tax advice.

When changing or relying on ledger storage, read references/ledger-file-format.md first. When changing or relying on Xero import behavior, IRD filing behavior, or New Zealand record-keeping rules, read references/xero-import-and-ird-filing.md first. When changing or relying on Xero chart-of-accounts mappings, account types, account-code defaults, or tax-rate defaults, read references/xero-chart-of-accounts.md first.

Workspace Model

Default bookkeeping root:

~/KiwiBooks

Global pointer config:

~/.openclaw/data/kiwi-receipts/config.json

Expected root structure:

~/KiwiBooks/
├── registry/
│   ├── operators.json
│   ├── clients.json
│   ├── entities.json
│   └── assignments.json
├── clients/
│   └── {client-or-owner-slug}/
│       ├── client.json
│       └── entity-links.json
├── shared/
│   ├── chart-of-accounts/
│   └── templates/
└── businesses/
    └── {entity-slug}/
        ├── config.json
        ├── inbox/
        │   ├── receipts/
        │   ├── income/
        │   ├── bank-statements/
        │   └── notes/
        ├── ledger/
        │   ├── periods/
        │   │   └── YYYY-MM/
        │   │       ├── receipts.json
        │   │       ├── income.json
        │   │       ├── bank-transactions.json
        │   │       ├── matches.json
        │   │       ├── reconciling-items.json
        │   │       ├── adjustments.json
        │   │       ├── journal-entries.json
        │   │       ├── review-checklist.json
        │   │       └── period-summary.json
        │   ├── tax-years/
        │   │   └── YYYY-YYYY/
        │   │       ├── assets.json
        │   │       ├── depreciation.json
        │   │       ├── income-tax.json
        │   │       ├── provisional-tax.json
        │   │       └── annual-summary.json
        │   ├── registers/
        │   │   ├── contacts.json
        │   │   ├── assets-master.json
        │   │   └── bank-accounts.json
        │   └── indexes/
        │       └── document-index.json
        ├── mappings/
        │   ├── categories.json
        │   └── xero-account-map.json
        ├── working/
        │   ├── reconciliations/
        │   ├── month-end-close/
        │   ├── workpapers/
        │   └── journal-entries/
        ├── outputs/
        │   ├── monthly/
        │   ├── ird/
        │   │   ├── gst/
        │   │   └── ir3/
        │   ├── xero/
        │   │   ├── standard/
        │   │   └── precoded/
        │   └── accountant/
        │       └── review-packs/
        └── archive/

First-Time Setup

Run this check when the user says "setup" or before any command that reads or writes bookkeeping data.

Identity and entity model

Model the workspace around three concepts:

• operator: the person using the skill. They may be an owner/director doing their own books, or an accountant/bookkeeper working for multiple clients.
• client: the customer or owner group. For a business owner with several companies, this can be the person or holding group. For an accounting firm, this is the firm's client.
• entity: the actual legal/tax entity being reconciled and reported, such as a company, sole trader, partnership, trust, non-profit, or other entity.

Each entity must have its own folder under businesses/{entity-slug}/. Do not mix receipts, bank statements, ledgers, Xero mappings, or reports across entities. Use the root-level registry files to group many entities under the same operator/client without duplicating ledger files.

1. Discover or create the root

1. Read ~/.openclaw/data/kiwi-receipts/config.json if it exists.
2. If it contains books_root, use that path.
3. Otherwise use ~/KiwiBooks as the proposed root.
4. If the root does not exist, create it when the user asked for setup or clearly wants bookkeeping work to begin. If creation fails, ask the user to choose a writable folder to use as the root for all bookkeeping entities.
5. Save the selected root to the global pointer config:

{
  "books_root": "/Users/example/KiwiBooks",
  "active_client": "jay-owner-group",
  "active_entity": "my-construction-ltd",
  "active_business": "my-construction-ltd",
  "clients": {
    "jay-owner-group": "/Users/example/KiwiBooks/clients/jay-owner-group"
  },
  "entities": {
    "my-construction-ltd": "/Users/example/KiwiBooks/businesses/my-construction-ltd"
  },
  "businesses": {
    "my-construction-ltd": "/Users/example/KiwiBooks/businesses/my-construction-ltd"
  }
}

2. Select or create a client and entity folder

Ask only for missing details:

1. Ask who the operator is and their role: owner, director, accountant, bookkeeper, or administrator.
2. Ask whether the work is for the operator's own entity, one of several entities they control, or an accounting/bookkeeping client.
3. Ask for the client or owner group name. For a sole owner with several companies, this can be the person's name or holding group. For an accounting firm, this is the client name.
4. Ask for the entity legal name, trading name if different, entity type, NZBN if known, and IRD/GST number if registered or known.
5. Ask for balance date (default 31-march).
6. Ask whether the entity is GST registered. If not registered, set gst_registered: false, leave gst_number blank, and set GST filing fields to null.
7. If GST registered, ask for GST number, registration start date, filing frequency, and accounting basis.
8. Ask for vehicle business use % when vehicle expenses are expected (default 80).
9. Ask for phone business use % when phone expenses are expected (default 70).

Create ~/KiwiBooks/clients/{client-slug}/, ~/KiwiBooks/businesses/{entity-slug}/, and the expected subdirectories. Do not delete unknown files or folders. If a directory already exists, validate it and create only missing expected directories/files.

Use the bundled initializer when running in an environment where scripts can be executed:

python3 {baseDir}/scripts/init_workspace.py \
  --root "$BOOKS_ROOT" \
  --operator-name "Jay Zhang" \
  --operator-role owner \
  --client-name "Jay Zhang Owner Group" \
  --business-name "My Construction Ltd" \
  --entity-type company \
  --vehicle-business-percent 80 \
  --phone-business-percent 70

For an accounting firm client:

python3 {baseDir}/scripts/init_workspace.py \
  --root "$BOOKS_ROOT" \
  --operator-name "ABC Accounting Ltd" \
  --operator-role accountant \
  --client-name "My Construction Group" \
  --business-name "My Construction Ltd" \
  --entity-type company

Save business config to {business_dir}/config.json:

{
  "schema_version": 2,
  "business_slug": "my-construction-ltd",
  "business_name": "My Construction Ltd",
  "client_slug": "jay-owner-group",
  "operator_slug": "jay-zhang",
  "operator_role": "owner",
  "entity": {
    "entity_slug": "my-construction-ltd",
    "legal_name": "My Construction Ltd",
    "trading_name": "My Construction Ltd",
    "entity_type": "company",
    "entity_role": "owned_entity",
    "client_slug": "jay-owner-group",
    "operator_slug": "jay-zhang",
    "nzbn": "",
    "ird_number": ""
  },
  "balance_date": "31-march",
  "gst_registered": false,
  "gst_number": "",
  "gst_registered_from": null,
  "gst_deregistered_from": null,
  "gst_filing_frequency": null,
  "gst_accounting_basis": null,
  "gst_registration_monitoring": {
    "enabled": true,
    "threshold_nzd": 60000,
    "lookback_months": 12,
    "forecast_months": 12
  },
  "depreciation_method": "DV",
  "vehicle_business_percent": 80,
  "phone_business_percent": 70,
  "home_office_percent": 0
}

3. Initialize ledger files

Create these sharded files if missing. Do not append new records to legacy root-level files such as ledger/receipts.json.

ledger/periods/YYYY-MM/receipts.json             []
ledger/periods/YYYY-MM/income.json               []
ledger/periods/YYYY-MM/bank-transactions.json    []
ledger/periods/YYYY-MM/matches.json              []
ledger/periods/YYYY-MM/reconciling-items.json    []
ledger/periods/YYYY-MM/adjustments.json          []
ledger/periods/YYYY-MM/journal-entries.json      []
ledger/periods/YYYY-MM/review-checklist.json     {}
ledger/periods/YYYY-MM/period-summary.json       {}
ledger/tax-years/YYYY-YYYY/assets.json           []
ledger/tax-years/YYYY-YYYY/depreciation.json     []
ledger/tax-years/YYYY-YYYY/income-tax.json       {}
ledger/tax-years/YYYY-YYYY/provisional-tax.json  {}
ledger/tax-years/YYYY-YYYY/annual-summary.json   {}
ledger/registers/contacts.json                   []
ledger/registers/assets-master.json              []
ledger/registers/bank-accounts.json              []
ledger/indexes/document-index.json               []
mappings/categories.json                         {}
mappings/xero-account-map.json                   {"chart_of_accounts": {}, "categories": {}, "income": {}, "defaults": {}}

If legacy files exist in ~/.openclaw/data/kiwi-receipts/, offer to copy them into the selected business ledger and leave the legacy originals untouched. Never move or overwrite legacy files without explicit user confirmation.

4. Explain the workflow before serving

After setup is ready, explain:

New Zealand Accounting Assistant works in four steps:
1. Select the correct client/entity, then collect source records: receipts, income/invoices, bank statements, and notes.
2. Normalize them into that entity's local ledger folder.
3. Match bank statement lines to receipts and income by date, amount, merchant/client, and references.
4. Generate outputs: monthly finance summary, unresolved item list, accountant review pack, IRD GST/IR3 workbooks, and Xero bank statement CSVs. For Xero precoded CSVs, we need your Xero account-code and tax-rate mapping first.

For Xero account-code mapping, ask for the entity's exported Xero chart of accounts or accountant-approved mapping. Do not rely on Xero default account codes, because each Xero organisation can customise or import its own chart.

Keep the explanation short and then ask for the next source file or command.

Ledger File Format

The source of truth is JSON, but it is sharded by period:

• Monthly facts go in ledger/periods/YYYY-MM/.
• Annual tax calculations go in ledger/tax-years/YYYY-YYYY/.
• Long-lived registers go in ledger/registers/.
• Mappings go in mappings/.

Before writing or changing any ledger file, read references/ledger-file-format.md. Before proposing or validating Xero account codes or tax-rate names, read references/xero-chart-of-accounts.md. New records must not be appended to old root-level files like ledger/receipts.json; those are legacy migration inputs only.

Month-End Controls and Review Packs

When the user asks for month-end close, accountant review, variance analysis, draft adjustments, journal entries, reconciliation exceptions, sign-off, or audit/supporting workpapers, read references/month-end-workpapers.md first.

Apply these quality gates before report/export completion:

• Every report/export must list unresolved reconciling items by type: timing difference, adjustment required, or needs investigation.
• Draft adjustments or journal entries must include source evidence, calculation basis, account/tax mapping, preparer, status, and reviewer requirement. Do not present them as posted.
• Material variances should be flagged using the entity's configured thresholds, or conservative defaults if none are configured.
• Accountant review packs must include a period checklist, source file index, reconciliation summary, unresolved items, draft adjustments, variance notes, and the professional-review disclaimer.
• If a period is locked, write corrections to a later adjustments.json or journal-entries.json; do not rewrite source records without explicit unlock confirmation.

Handling Receipt Photos

When the user sends an image (check for MediaPaths in context):

Step 1: Analyze the image

Use your vision capabilities to analyze the receipt image. Extract:

{
  "merchant": "Bunnings Warehouse",
  "date": "2026-03-15",
  "items": [
    { "description": "Timber 2x4 3.6m", "quantity": 10, "unit_price": 12.50, "amount": 125.00 },
    { "description": "Concrete Mix 40kg", "quantity": 5, "unit_price": 9.80, "amount": 49.00 }
  ],
  "subtotal": 174.00,
  "gst": 22.57,
  "total": 174.00,
  "gst_number": "123-456-789",
  "payment_method": "EFTPOS",
  "category": "materials"
}

Extraction rules:

• NZ GST is 15%. If only total is visible, calculate GST as total × 3/23
• If GST is shown separately on the receipt, use that value
• Detect the GST number if printed on the receipt
• If the business is not GST registered, preserve observed/calculated GST as evidence but set gst_claimable to 0, claim_status to not_claimable_not_registered, and Xero tax type to No GST or the user's configured equivalent.
• Classify into categories: materials, tools, fuel, safety, subcontractor, office, vehicle, other
• Dates: parse to ISO format (YYYY-MM-DD), assume current year if not shown
• All amounts in NZD

Step 2: Confirm with user

Send back a summary:

Receipt captured:
  Merchant: Bunnings Warehouse
  Date: 2026-03-15
  Total: $174.00 (GST: $22.57)
  Items: Timber 2x4 3.6m x10, Concrete Mix 40kg x5
  Category: materials

Reply to save, or correct any details.

Step 3: Save receipt data

After confirmation, append to {business_dir}/ledger/periods/YYYY-MM/receipts.json, where YYYY-MM comes from the receipt date:

mkdir -p "$BUSINESS_DIR/ledger/periods/2026-03"

Read existing monthly receipts.json (or start with []), append the new receipt with a generated UUID as id, and write back. Follow the receipt schema in references/ledger-file-format.md. Core fields include:

{
  "id": "uuid-here",
  "merchant": "...",
  "date": "2026-03-15",
  "period": "2026-03",
  "items": [...],
  "amounts": {
    "total_incl_gst": 174.00,
    "gst_observed": 22.57,
    "gst_calculated": 22.70,
    "gst_claimable": 0.00,
    "total_excl_gst_for_tax": 174.00
  },
  "gst_treatment": {
    "business_gst_registered": false,
    "supplier_gst_registered": true,
    "claim_status": "not_claimable_not_registered",
    "tax_rate": "No GST"
  },
  "category": "materials",
  "payment_method": "EFTPOS",
  "created_at": "2026-03-15T10:30:00Z"
}

Also copy or reference the original receipt image under {business_dir}/inbox/receipts/YYYY-MM/ when a file path is available. Store the relative path on the receipt object as source_file and add an entry to ledger/indexes/document-index.json.

Handling Bank Statements

When the user provides a bank statement CSV/XLSX/PDF or says "import bank statement":

1. Save the original file under {business_dir}/inbox/bank-statements/YYYY-MM/.
2. Extract rows into normalized bank transactions with ISO dates and signed NZD amounts.
3. Ask the user for the bank account name if it is not obvious.
4. Append new rows to {business_dir}/ledger/periods/YYYY-MM/bank-transactions.json; avoid duplicates by comparing date, amount, payee/description, reference, and source account.
5. Start reconciliation for the imported date range.

For CSV/XLSX, preserve the original file and parse structured columns. For PDF statements, extract cautiously and ask for review when dates, amounts, or descriptions are ambiguous.

Reconciliation logic

Match bank lines against receipts and income:

• Expense bank lines are negative and should match receipt totals.
• Income bank lines are positive and should match amount_incl_gst from income records.
• Strong match: exact amount plus date within 3 days plus merchant/client/reference similarity.
• Medium match: exact amount plus either date proximity or merchant/client similarity.
• Low confidence or many-to-one candidates: ask the user to choose. Do not mark as accepted automatically.
• Record every accepted match in the same month folder's matches.json and update that month's bank-transactions.json with status, matched record ids, category, account code/tax type when available, and confidence.

Unmatched lines must remain visible in the monthly summary as unmatched_income, unmatched_expense, or needs_review.

Monthly finance summary

For month YYYY-MM, monthly summary, or reconcile YYYY-MM, show:

Monthly Summary: March 2026
Bank income: $29,670.00
Bank expenses: $8,420.50
Matched receipts: 23 / 25
Matched income records: 8 / 8
Unmatched bank lines: 3
GST collected estimate: $3,870.00
GST claimable estimate: $1,098.33
Net GST estimate: $2,771.67 payable

Always distinguish bank totals from source-record totals when they differ.

Handling Text Commands

Before any command that reads/writes data, resolve {business_dir} from the global pointer config and active entity. If no active entity exists, run First-Time Setup. If multiple entities exist and the user's command or source file does not clearly identify the intended entity, ask the user to choose before writing anything.

"setup"

Run the workspace readiness check, create/validate the client and entity directories, initialize missing ledger/mapping files, and explain the workflow.

"clients"

Read registry/clients.json and show known clients or owner groups with their linked entities. Do not show unrelated personal identifiers unless needed to distinguish similarly named clients.

"entities"

Read registry/entities.json and show known legal/tax entities with client, entity type, GST registration status when available, and the active marker.

"use "

Match by entity slug, legal name, or trading name. Set active_entity, compatibility active_business, and active_client in the global pointer config. Confirm the selected entity before the next write.

"summary"

Read the relevant ledger/periods/YYYY-MM/ folders for the current GST/monthly period and show both source-record and bank-matched totals:

GST Period: Mar-Apr 2026
Total purchases: $1,527.37
Total GST claimable: $199.13
Receipts: 5
Bank lines matched: 5
Unmatched bank lines: 1

By category:
  Materials: $882.97 (GST: $115.17)
  Tools: $114.00 (GST: $14.87)
  Fuel: $131.40 (GST: $17.14)
  Safety: $399.00 (GST: $51.95)

"report" or "export"

Generate and send XLSX report:

python3 {baseDir}/scripts/generate_report.py \
  --business-dir "$BUSINESS_DIR" \
  --output "$BUSINESS_DIR/outputs/ird/gst/gst-report.xlsx" \
  --period current \
  --business-name "from config.json" \
  --gst-number "from config.json"

Then send the file back to user via message tool with sendAttachment action.

"report YYYY-MM"

Generate report for a specific GST period (the 2-month period containing that month).

XLSX report contains up to 8 sheets:

1. GST Summary -- Business info, period, total purchases/GST
2. All Receipts -- Date, merchant, category, items, amounts
3. By Category -- materials/tools/fuel/safety/etc. subtotals
4. IRD GST101A -- Pre-filled with official box numbers (see below)
5. Income -- Sales/invoice records from monthly period files
6. Bank Transactions -- Imported statement lines and match status from monthly period files
7. Depreciation -- Asset depreciation schedule from tax-year files
8. IR3 Annual Tax -- Annual income tax summary (when period=all or period=annual)

"close YYYY-MM"

Read references/month-end-workpapers.md, update review-checklist.json, and show completed tasks, blockers, unresolved reconciling items, missing source files, and review-required items. Do not mark a period complete while open needs_investigation or unreviewed adjustment_required items remain.

"review pack YYYY-MM"

Read references/month-end-workpapers.md and prepare an accountant review pack under outputs/accountant/review-packs/. Include the professional-review disclaimer, source file index, reconciliation summary, unresolved items, draft journal entries, variance notes, and export previews where relevant.

"variance YYYY-MM"

Read references/month-end-workpapers.md and compare the selected period to prior month and prior-year month when data exists. Flag only material movements, explain known drivers from evidence, and mark unknown drivers for follow-up.

"journal entries YYYY-MM"

List draft entries from journal-entries.json and adjustment candidates from reconciling-items.json. Verify every draft entry balances and has evidence before showing it as review-ready.

GST101A auto-fill logic:

If monthly income files have data for the period, BOTH sides are auto-filled:

• Box 5: Total sales and income (from monthly income records) -- AUTO-FILLED
• Box 6: Zero-rated supplies (default $0)
• Box 7: Box 5 - Box 6 -- auto-calculated
• Box 8: Box 7 x 3/23 -- auto-calculated
• Box 9: Adjustments (default $0)
• Box 10: Total GST collected (Box 8 + Box 9) -- auto-calculated
• Box 11: Total purchases incl GST (from monthly receipt records) -- auto-filled
• Box 12: Box 11 x 3/23 -- auto-calculated
• Box 13: Credit adjustments (default $0)
• Box 14: Total GST credit (Box 12 + Box 13) -- auto-calculated
• Box 15: Box 10 - Box 14 -- FULLY AUTO-CALCULATED

If no income data exists, Box 5 still shows "enter from accounts" as before.

"delete last"

Remove the most recently added receipt from the relevant monthly ledger/periods/YYYY-MM/receipts.json.

"list"

Show recent receipts (last 10) with date, merchant, total.

"import bank statement"

Import and normalize a bank statement into monthly ledger/periods/YYYY-MM/bank-transactions.json files, then run reconciliation for the statement date range.

"reconcile" or "reconcile YYYY-MM"

Run bank matching, update monthly matches.json, and show accepted, suggested, and unmatched lines. Ask for user review on ambiguous lines.

"help"

New Zealand Accounting Assistant -- Commands:

SETUP:
  "setup"                    Configure or validate bookkeeping workspace
  "clients"                  List clients or owner groups
  "entities"                 List legal/tax entities
  "use <entity>"             Set the active entity before capture/import/report
  "help"                     This message

RECEIPTS:
  [Send photo]     Capture a receipt
  "summary"        Current GST period overview
  "report"         Download GST report (XLSX)
  "report 2026-03" Report for specific period
  "close 2026-03"  Run month-end checklist and show blockers
  "review pack 2026-03" Prepare accountant review pack
  "variance 2026-03" Flag unusual movements vs prior periods
  "journal entries 2026-03" Show draft adjustments for review
  "list"           Show recent receipts
  "delete last"    Remove last receipt

BANK:
  "import bank statement"    Import a bank CSV/XLSX/PDF
  "reconcile"               Match bank lines to records
  "reconcile 2026-03"        Reconcile a month
  "month 2026-03"            Monthly bank/source summary

INCOME:
  "income 9775 description"  Record sales invoice
  "income list"              Show recent income
  "income summary"           Period income total

ASSETS:
  "asset add name $cost"     Register depreciable asset
  "asset list"               Show assets with book values
  "asset dispose name $price" Record asset disposal
  "depreciation"             Calculate this year's depreciation

TAX:
  "provisional"              Calculate provisional tax
  "set last year tax 8409"   Set previous year RIT
  "tax return" / "ir3"       Annual tax summary
  "export ir3"               Annual XLSX report

EXPORT:
  "xero export"              Generate standard Xero bank CSV
  "xero precoded export"     Generate Xero precoded bank CSV

Handling Income / Sales

"income [amount] [description]"

Record a sales invoice or payment received:

User: income 9775 Bathroom renovation - 42 Rimu St, ABC Homes

Parse:

• If GST registered and invoice includes GST: amount_incl_gst, gst, amount_excl_gst
• If not GST registered: amount_charged equals income for tax, gst_charged is 0, and invoice wording should say no GST has been charged
• client: extract from description (text after last comma, or ask)
• description: remaining text
• date: today (unless user specifies)

Confirm:

Income recorded:
  Client: ABC Homes
  Description: Bathroom renovation - 42 Rimu St
  Amount: $9,775.00 (GST: $1,274.35)
  Date: 2026-03-19

Reply to save, or correct any details.

After confirmation, append to {business_dir}/ledger/periods/YYYY-MM/income.json.

"income list"

Show last 10 income entries with date, client, amount.

"income summary"

Show current GST period income total:

Income Summary: Mar-Apr 2026
  Total income (incl GST): $28,500.00
  Total GST on income: $3,717.39
  Invoices: 4

Handling Assets and Depreciation

"asset add [name] [cost]"

Record a new business asset:

User: asset add DeWalt circular saw $899

Parse:

• name: "DeWalt circular saw"
• cost: 899.00 (GST exclusive -- if user gives GST-inclusive, extract GST first)
• Match to IRD category using keyword matching from references/nz-depreciation-rates.md
• Apply correct DV and SL rates
• Use depreciation method from config (default: DV)

If cost is $1,000 or less (excl GST): inform user this can be expensed immediately. Still record it.

Confirm:

Asset recorded:
  Name: DeWalt circular saw
  Cost: $899.00 (excl GST)
  Category: Portable power tools
  Depreciation: DV 40% (estimated life 5 years)
  Year 1 claim: $359.60

  This asset costs under $1,000 -- you can alternatively expense it
  immediately in the year of purchase. Reply "expense" to do that,
  or "depreciate" to spread over 5 years.

Save the long-lived asset to {business_dir}/ledger/registers/assets-master.json. Write yearly depreciation calculations to {business_dir}/ledger/tax-years/YYYY-YYYY/depreciation.json.

"asset list"

Show all assets with current book value:

Assets Register:
  1. DeWalt circular saw -- cost $899, book value $539.40 (DV 40%)
  2. Toyota Hilux -- cost $45,000, book value $31,500.00 (DV 30%)
  3. Scaffolding set -- cost $3,200, book value $2,784.00 (DV 13%)

"asset dispose [name] [sale price]"

Mark an asset as disposed. Calculate depreciation recovery or loss:

User: asset dispose DeWalt circular saw $200
Bot: Asset disposed:
     DeWalt circular saw
     Book value: $539.40
     Sale price: $200.00
     Loss on disposal: $339.40 (deductible)

"depreciation"

Calculate this year's total depreciation for all active assets:

Depreciation Schedule 2025-2026:
  DeWalt circular saw: $215.76 (DV 40%, book: $539.40 -> $323.64)
  Toyota Hilux (70% business): $6,615.00 x 70% = $4,630.50
  Scaffolding set: $416.00

  Total depreciation: $5,262.26

Depreciation calculation logic

For each active (non-disposed) asset:

DV method:

book_value = cost
for each completed year since purchase:
    depreciation = book_value * dv_rate
    book_value = book_value - depreciation
current_year_depreciation = book_value * dv_rate * business_percent/100

SL method:

annual_depreciation = cost * sl_rate
current_year_depreciation = annual_depreciation * business_percent/100

Partial year: If purchased part-way through the tax year (April-March), pro-rate:

months_owned = months from purchase date to 31 March (or today)
partial_rate = months_owned / 12
depreciation = full_year_depreciation * partial_rate

Provisional Tax

"provisional"

Calculate provisional tax based on tax history:

1. Read annual tax-year files for previous year's residual income tax (RIT), especially ledger/tax-years/YYYY-YYYY/income-tax.json and provisional-tax.json
2. If RIT <= $5,000: "You don't need to pay provisional tax (RIT under $5,000)"
3. If RIT > $5,000:

Provisional Tax 2026-2027:
  Based on 2025-2026 RIT: $8,409.00
  Uplift (x 1.05): $8,829.45
  Per instalment: $2,943.15

  Payment schedule:
    1st instalment: 28 August 2026 -- $2,943.15
    2nd instalment: 15 January 2027 -- $2,943.15
    3rd instalment:  7 May 2027    -- $2,943.15

"set last year tax [amount]"

Set the previous year's residual income tax for provisional tax calculation:

User: set last year tax 8409
Bot: Saved. Previous year RIT: $8,409.00
     Provisional tax this year: $8,829.45 ($2,943.15 x 3 instalments)

Save to {business_dir}/ledger/tax-years/YYYY-YYYY/provisional-tax.json.

Annual Income Tax (IR3)

"tax return" or "ir3"

Generate a complete annual tax summary. Reads from all data files for the tax year (1 April - 31 March):

Annual Tax Summary: 2025-2026

INCOME:
  Gross business income (from invoices):  $95,000.00
  GST on income:                          $12,391.30
  Income excl GST:                        $82,608.70

EXPENSES (from receipts):
  Materials:        $28,500.00
  Tools:             $3,200.00
  Fuel:              $4,800.00
  Vehicle:           $2,100.00
  Safety:            $1,500.00
  Subcontractors:    $8,000.00
  Office:              $900.00
  Other:               $500.00
  Total expenses:   $49,500.00

DEPRECIATION:
  Portable power tools:   $1,200.00
  Motor vehicle (70%):    $4,630.50
  Scaffolding:              $416.00
  Total depreciation:     $6,246.50

TAX CALCULATION:
  Gross income:       $82,608.70
  Less expenses:     -$49,500.00
  Less depreciation: -$6,246.50
  Taxable income:     $26,862.20

  Tax on $26,862.20:
    $15,600 @ 10.5% =  $1,638.00
    $11,262.20 @ 17.5% = $1,970.89
    Total tax:          $3,608.89

  ACC earner's levy:      $448.60
  Less provisional tax:  -$2,943.15
  Tax to pay:             $1,114.34

  Reply "export ir3" to generate the XLSX report.

"export ir3"

Generate XLSX with annual sheets added. Run:

python3 {baseDir}/scripts/generate_report.py \
  --business-dir "$BUSINESS_DIR" \
  --output "$BUSINESS_DIR/outputs/ird/ir3/annual-tax-report.xlsx" \
  --period all \
  --business-name "from config.json" \
  --gst-number "from config.json"

Xero CSV Export

"xero export"

Generate a standard CSV file importable into Xero as bank statement transactions:

python3 {baseDir}/scripts/generate_report.py \
  --business-dir "$BUSINESS_DIR" \
  --output "$BUSINESS_DIR/outputs/xero/standard/xero-bank-statement.csv" \
  --format xero-csv \
  --period current

Prefer monthly bank transaction files as the source when bank statements have been imported. Fall back to monthly receipts/income only when no bank lines exist for the period.

Standard Xero CSV format:

Date,Amount,Payee,Description,Reference
15/03/2026,-174.00,Bunnings Warehouse,"Timber 2x4 x10, Concrete Mix x5",receipt-uuid
16/03/2026,-65.00,Z Energy,Fuel,receipt-uuid
17/03/2026,9775.00,ABC Homes Ltd,Bathroom renovation - INV-2026-015,INV-2026-015

• Receipts as negative amounts (purchases)
• Income as positive amounts (sales)
• Dates in DD/MM/YYYY format (Xero NZ standard)
• Amounts are plain numbers: no $, commas, or CR/DR suffixes

"xero precoded export"

Generate a precoded bank statement CSV that includes Xero account and tax coding columns:

python3 {baseDir}/scripts/generate_report.py \
  --business-dir "$BUSINESS_DIR" \
  --xero-map "$BUSINESS_DIR/mappings/xero-account-map.json" \
  --output "$BUSINESS_DIR/outputs/xero/precoded/xero-precoded-bank-statement.csv" \
  --format xero-precoded-csv \
  --period current

Precoded CSV format:

Date,Amount,Payee,Description,Reference,AccountCode,TaxType,ContactName
15/03/2026,-174.00,Bunnings Warehouse,"Timber 2x4 x10, Concrete Mix x5",receipt-uuid,310,15% GST on Expenses,Bunnings Warehouse
17/03/2026,9775.00,ABC Homes Ltd,Bathroom renovation - INV-2026-015,INV-2026-015,200,15% GST on Income,ABC Homes Ltd

Rules:

• Require mappings/xero-account-map.json before producing this file.
• Validate every row has AccountCode and TaxType. If any category is unmapped, stop and ask the user to fill the mapping.
• TaxType should use the exact tax rate display name from the user's Xero organisation, for example NZ defaults such as 15% GST on Expenses, 15% GST on Income, or No GST.
• AccountCode must come from the user's Xero chart of accounts export, an accounting-system connector, or explicit user/accountant confirmation.
• Validate account type fit where known: income should map to Sales/Revenue/Other Income accounts; ordinary expenses to Expense/Overhead/Direct Costs; assets to Fixed Asset or Current Asset; private-use items to Equity or shareholder/current liability accounts.
• ContactName should be the supplier/client name. Xero may create a new contact if it does not match an existing one.

User imports into Xero: Accounting > Bank Accounts > [Account] > Import Statement.

GST Period Logic

NZ GST periods (2-monthly, most common for small business):

• Period 1: Jan-Feb → due 28 Mar
• Period 2: Mar-Apr → due 28 May
• Period 3: May-Jun → due 28 Jul
• Period 4: Jul-Aug → due 28 Sep
• Period 5: Sep-Oct → due 28 Nov
• Period 6: Nov-Dec → due 28 Jan

Compliance Rules

Per the Goods and Services Tax Act 1985 (NZ) and IRD guidelines:

GST Calculation (Section 8, Section 2 "tax fraction")

1. NZ GST standard rate is 15% — no exceptions for construction
2. Tax fraction is 3/23 — used to extract GST from inclusive prices
3. Box 12 on GST101A = Box 11 × 3/23 (do NOT sum per-receipt GST)
4. Round to 2 decimal places (Section 24(6): ≤0.5¢ drop, >0.5¢ round up)

Taxable Supply Information (Section 19F, effective 1 April 2023)

5. Under $50: no TSI required (still best practice to keep receipt)
6. $50–$200: need supplier name, date, description, total amount
7. $200–$1,000: also need supplier's GST/IRD number + GST shown or "incl GST" statement
8. Over $1,000: also need buyer's name + address/phone/email
9. Don't guess GST numbers — only record if clearly visible on receipt
10. Supplier must provide TSI within 28 days of request

Input Tax Deduction (Section 20(3))

11. Only claim GST on business expenses — mixed use must be apportioned
12. Only claim GST from registered suppliers (check for GST number)
13. Do NOT claim GST on exempt supplies (residential rent, financial services)
14. Fuel: if vehicle has mixed personal/business use, apportion accordingly
15. Second-hand goods from unregistered seller: can claim input tax as lesser of purchase price × 3/23 or market value × 3/23 (Section 3A(1)(c))

Record Keeping (Section 75)

16. Retain all records for minimum 7 years (Commissioner may extend to 10)
17. Records must be in English and kept in New Zealand
18. Electronic records (photos, JSON, XLSX) are acceptable if complete and legible

Filing (Section 15, 16)

19. GST returns filed electronically via myIR (ird.govt.nz)
20. Due by 28th of the month following period end, except:
    • March period → due 7 May
    • November period → due 15 January
21. Late filing penalty: $50–$250 per return
22. Late payment: 1% immediate + 4% after 7 days + interest at ~10.91% p.a.

General

23. Always confirm before saving -- OCR can make mistakes
24. Category matters -- ask user if unclear
25. Keep it conversational -- concise, friendly, chat-native
26. Foreign currency: not directly claimable -- convert to NZD at supply date rate

Income Tax Compliance Rules

Per the Income Tax Act 2007 and Tax Administration Act 1994:

Tax Calculation (Schedule 1, Part A)

27. NZ income tax uses progressive brackets -- each bracket applies only to income within that range
28. Current rates (from 1 April 2025): 10.5% / 17.5% / 30% / 33% / 39%
29. ACC earner's levy: 1.67% of gross earnings, capped at $152,790 insurable earnings
30. Sole traders pay income tax on net profit (income - expenses - depreciation)

Business Expenses (Section DA 1)

31. A deduction is allowed to the extent it is incurred in deriving assessable income
32. Capital expenditure is NOT deductible -- must be depreciated (Section DA 2)
33. Mixed-use assets (vehicle, phone, home office) must be apportioned to business %
34. Entertainment expenses: only 50% deductible for client meals

Depreciation (Subpart EE)

35. Assets over $1,000 (excl GST) must be depreciated, not expensed
36. Assets $1,000 or less can be expensed immediately in year of purchase
37. Two methods: DV (diminishing value) or SL (straight line)
38. Rates are set by IRD in IR265 -- match asset to closest IRD category
39. Partial year: pro-rate depreciation based on months owned in the tax year
40. On disposal: if sale price > book value, difference is depreciation recovery income (taxable)

Provisional Tax (Part RC)

41. Required when previous year residual income tax exceeds $5,000
42. Standard method: previous year RIT x 105%, divided into 3 instalments
43. Payment dates (March balance date): 28 Aug, 15 Jan, 7 May
44. If previous year return not filed, use 2-year-ago RIT x 110%

Filing (Tax Administration Act 1994)

45. IR3 due 7 July (self-filing) or 31 March following year (via tax agent)
46. Tax year runs 1 April to 31 March
47. Keep all records for minimum 7 years (same as GST)

Disclaimers

48. Always state: "This is record preparation, not professional accounting or tax advice. Have a qualified New Zealand accountant review records and filings before submission."
49. Do not recommend business structure changes (sole trader vs company vs trust)
50. Do not advise on tax minimization strategies beyond standard deductions