Month-end close

The Engagements tab is where a firm closes a client's books for a given month. It bundles the categorisation, AI tax check, and review-sign-off work into one structured workflow that ends with the period sealed.

Open from any client → Engagements.

What an engagement is

A container for one month-end close. Today there's exactly one kind — Month-end close (month_end_close) — covering a single calendar month. The engagement holds:

• The period (e.g. May 2026)
• A list of transactions in that period
• Counts of uncategorised and unreviewed rows
• A lifecycle state — Open → In Review → Closed

You can have at most one open engagement per kind per month — the database enforces this so you don't accidentally start two May closes at once.

Future engagement kinds (annual close, tax returns) will share the same shell.

Opening an engagement

Restricted to Partner / Manager roles.

1. Engagements tab → New engagement
2. Pick the month (last 18 months are selectable)
3. Save

Kiravy creates the engagement in Open state and computes initial counts. You can have multiple months open at once (May, June, July) — they don't block each other. State must move forward (Open → In Review → Closed); you can't skip steps.

Inside an engagement

Three tabs: Review queue, Uncategorised, and Reconciliation.

Review queue tab

Lists every transaction in the period that hasn't been marked reviewed (reviewed_at is null).

Use it like this:

1. Skim the rows — they show vendor, amount, account, tax flag
2. Tick the checkbox next to entries you're satisfied with
3. Mark N reviewed button at the top — batch-marks all selected
4. Reviewed rows fade from the list

The point of the Review queue is bulk sign-off. Reviewing one transaction at a time from the main Transactions tab would be tedious; the engagement view is built for closing a period systematically — you might mark 200 rows reviewed in one session.

There's also a Run tax check button (Partner / Manager only) which fires Kiravy AI's deductibility classification across every unreviewed row. AI tags each one as deductible / non-deductible / partial / unknown — you then review the tags before ticking.

Uncategorised tab

Anything in the period without an account_code lands here. Common causes:

• Bank-feed import that didn't auto-match a CoA code
• CSV upload where the account column was blank
• Manual entry where the user skipped the account field
• AI receipt extraction where the AI couldn't infer the right code

The fix:

1. Each row has an inline account dropdown showing the client's chart of accounts
2. Pick the right code
3. Click the ✓ to save
4. Row vanishes from the list

Up to 200 most-recent uncategorised entries shown — if you have more than that, you've got bigger problems than a UI page-size.

Reconciliation tab

The first check here is the ledger's own proof: total debits equal total credits for the period. Because every transaction, invoice, and payment posts a balanced journal entry, the books should always balance — the Trial balance report is where you see this in full, and a mismatch points to something a human needs to investigate before sealing the period.

(This tab is still being expanded — your firm's needs will shape what checks land here.)

The lifecycle — Open → In Review → Closed

The state machine is one-way: you cannot reopen a closed engagement.

What "Closing" actually does

1. Seals the period — once a month is locked, Kiravy hard-rejects any new or back-dated entry dated in that month; this is enforced, not just a convention. (Voiding an existing document still works, because the reversal is dated in the current open period.) See Period lock.
2. Back-fills engagement_id on every transaction in the period that doesn't already have one. This is how future reports filter by engagement (e.g. "all May 2026 expenses").
3. Records the close in audit_logs with timestamp + closing user
4. Sets closed_at and closed_by

AI tax deductibility — what it does and doesn't

The Run tax check button on the Review queue triggers an AI pass over every unreviewed transaction. For each, it returns one of:

• deductible — confidently allowed for tax deduction
• non_deductible — confidently not allowed (e.g. personal expense, entertainment over the limit)
• partial — partly deductible (specific Malaysian rules apply)
• unknown — AI couldn't decide

It writes the verdict to the transaction's tax_deductibility field. The Transactions tab's Tax filter then lets you triage flagged rows.

You can override any AI verdict on the transaction detail page (Senior+ role). The override sticks across future AI runs — Kiravy never re-classifies a manually-overridden row.

Permissions matrix

When to use engagements vs ad-hoc work

• Use the Transactions tab for one-off edits, recording a specific entry, looking something up
• Use an engagement for the periodic batch — reviewing all of May systematically before issuing financials

Most firms will open an engagement the first business day of each month, work through it over the following weeks, and close it once management accounts are signed off.

What's coming

• Engagement-scoped reports — P&L and balance sheet generated from a single engagement's data
• Annual close engagement kind
• Reconciliation tab built-out — bank rec and suspense balance checks on top of the trial-balance proof

What's next

• Transactions — the underlying ledger view
• AI assistant — what else Kiravy AI does inside a client (soon)
• P&L report — the deliverable an engagement helps you produce (soon)