Briefcase

View saved version →

---
name: document-submission
description: Submit a bill, receipt, bank statement or supplier statement to a Briefcase client, choosing between direct upload, a browser upload link and the client's forwarding email, then track processing to the resulting transaction. Use when the user shares a document or asks to upload, send or file something into Briefcase.
---

# Submitting documents to Briefcase

## Choose the client

Resolve the client with `briefcase_list_clients` and confirm it with the user when the name is ambiguous. Ask for a business or property only when the client has more than one (`briefcase_get_reference_data` with `kind: businesses` or `properties`).

## Prepare the upload

Call `briefcase_create_document_upload` with the file name, MIME type, size if known, and the user's note (for example "Pay from the deposit account" or "Split 60/40 with the Manchester office"). The response gives three routes:

1. **You can transfer the file.** `PUT` the original bytes to `upload_url` with the returned headers, then call `briefcase_submit_document` with the `upload_id` and a fresh `idempotency_key`.
2. **You cannot transfer the file.** Give the user `browser_upload_url`. They open it, sign in, check the client and note, choose the file and press Upload. The link expires after one hour and only accepts the prepared file type.
3. **Email.** Give the user `forwarding_email` and tell them to put the note in the email body.

Never fabricate file contents and never submit a file the user did not provide.

## Track processing

`briefcase_submit_document` returns an operation. Poll `briefcase_get_operation` no more than once every few seconds until it reaches a final state, then report:

- the transaction, bank statement or supplier statement that was created, with its status;
- an archive as duplicate or not-a-transaction, with the reason;
- a failure, with the message, and suggest re-uploading a clearer copy.

On Autopilot clients a submitted document may publish automatically. Say so before submitting when `briefcase_get_client` shows Autopilot is on.

## Retries and refusals

Retry a failed `briefcase_submit_document` with the same `idempotency_key`; Briefcase will not create a second candidate. A `FORBIDDEN` result means the user cannot upload for this client or assistant changes are paused. `VALIDATION_ERROR` on file type or size means the document must go through the app or email instead.

View saved version →

---
name: expense-claims
description: Group a claimant's receipts into an expense claim in Briefcase, add or remove receipts, check the claim's state and publish it with a preview first. Use when the user asks about employee or director expenses, reimbursing out-of-pocket costs, or what is still waiting to be claimed.
---

# Expense claims in Briefcase

An expense claim bundles unpublished receipts paid personally by one claimant, so the business owes that person rather than a supplier. Creating and editing claims needs the expense claim create permission; publishing needs expense claim publish. `FORBIDDEN` means the user lacks one of them or assistant changes are paused.

## Find what to claim

- `briefcase_list_expense_claims` and `briefcase_get_expense_claim` show existing claims, their receipts and whether they are published.
- `briefcase_list_transactions` with `awaiting_review: true` finds unpublished receipts. Confirm with the user which ones the claimant paid personally; do not guess from the supplier name.
- `briefcase_get_reference_data` with `kind: claimants` gives the claimant contacts.

## Build the claim

1. `briefcase_create_expense_claim` with the `transaction_ids`, the claimant as `supplier_id`, the `claim_date` and a fresh `idempotency_key`. All receipts must share one currency; a mismatch returns `VALIDATION_ERROR`, so split them into separate claims.
2. `briefcase_add_claim_transactions` adds more unpublished receipts to a claim that is not yet published.
3. `briefcase_remove_claim_transaction` takes one receipt back out of an unpublished claim.

Fix a receipt's own coding with `briefcase_update_transaction` before publishing (see the transaction review skill).

## Publish

1. `briefcase_publish_expense_claim` with `mode: preview`. Summarise the claimant, claim date, currency, total, the destination in the ledger and any blockers.
2. `claim_date`, `currency` and `claimant_contact_id` override the stored values only when the user asks. For Xero, `publish_destination` and `bills_to_pay_status` choose how the claim lands; for QuickBooks, `quickbooks_publish_destination`.
3. Execute only after the user agrees, with the `preview_id`, `mode: execute` and a fresh `idempotency_key`.

Publishing posts the claim to the ledger as money owed to the claimant. Say so before executing, and read the claim back with `briefcase_get_expense_claim` afterwards.

View saved version →

---
name: financial-close-review
description: Review and maintain prepayments, deferred income, accruals and fixed asset depreciation for a Briefcase client at period end, read the close trackers, draft new schedules and adjustments, and publish them with a preview first. Use when the user asks about month-end, year-end, prepayment or accrual schedules, depreciation, or what is left to post for a period.
---

# Financial close review in Briefcase

Everything here needs the FINANCIAL_CLOSE permission in Briefcase. If a call returns `FORBIDDEN`, tell the user which permission is missing rather than trying another tool.

## Read before you write

1. `briefcase_get_close_tracker` for the client and period. Explain the grid: opening balance, movement in the period, closing balance, and which periods are posted, due or paused.
2. `briefcase_list_close_items` for one `module` at a time (`prepayment`, `deferred_income`, `accrual`, `fixed_asset`). The list gives each schedule's period summary; `briefcase_get_close_item` gives its periods (set `period_start_date` and `period_end_date` for a long schedule) and the detail the user asks about, including the source transaction where there is one.
3. Cross-check with `briefcase_list_transactions` when the user suspects a prepayment was published as a straight expense.

Report amounts in the client's currency exactly as returned. Do not recompute schedules yourself; the tracker is authoritative.

## Draft changes

- `briefcase_create_close_item` creates drafts only. Accruals are created as a draft adjustment and are not posted. Always send a fresh `idempotency_key`.
- `briefcase_update_close_item` edits a draft or the future periods of a schedule. For an accrual it edits the adjustment amount, date and lines, not the recurring parent's estimate.
- Use `briefcase_get_reference_data` for balance sheet and expense accounts, and quote the account the schedule will post to.

## Publish, archive, restore

- Preview first: `mode: preview` on `briefcase_publish_close_item`, `briefcase_archive_close_item` or `briefcase_unarchive_close_item`. Summarise the journals that would post or reverse, the periods affected and any lock-date conflicts.
- Execute only after the user agrees, with the `preview_id`, `mode: execute` and a fresh `idempotency_key`.
- Publishing a schedule starts posting in Briefcase and the connected ledger; archiving reverses what was posted and stops future periods. Say this plainly before executing.
- Published fixed assets and committed accrual adjustments cannot be edited here; direct the user to the Briefcase app.

## Wrap up

Re-read the tracker after publishing so the user sees the updated position, and remind them the changes appear under Settings → AI assistants → Activity.

View saved version →

---
name: ledger-reports
description: Read and explain a Briefcase Ledger client's profit and loss, balance sheet, aged creditors and aged debtors, compare periods, and drill from a report line into the journals and source documents behind it. Use when the user asks how a client is doing, what makes up a balance, why a figure moved, or who owes or is owed money.
---

# Ledger reports in Briefcase

These tools only work for Briefcase Ledger clients. Check `ledger_type` from `briefcase_list_clients` or `briefcase_get_client`; for a Xero or QuickBooks client they return `UNSUPPORTED_CAPABILITY`, so tell the user to read the reports in that ledger instead. Everything here needs the Ledger view permission; `FORBIDDEN` means the user lacks it.

## Pick the report

- **Profit and loss:** `briefcase_get_profit_and_loss` with `start_date` and `end_date`. Add `comparison_start_date` and `comparison_end_date` for "this month against last month" or "this year against last year". Filter with `business_id` or `property_id` only when the user asks about one business or property (`briefcase_get_reference_data` with `kind: businesses` or `properties`).
- **Balance sheet:** `briefcase_get_balance_sheet` with `as_at` (defaults to today) and optionally `comparison_as_at`. Retained earnings is the profit to date shown within equity, so `total_equity` equals `net_assets`.
- **Aged creditors or debtors:** `briefcase_get_aged_report` with `subledger: ACCOUNTS_PAYABLE` (creditors) or `ACCOUNTS_RECEIVABLE` (debtors) and `as_at`. Totals cover every contact; contacts come largest balance first, 25 per page with up to 10 invoices each. Page with `after` for more contacts, and set `contact_id` to see one contact's invoices in full.

Resolve relative periods ("last quarter", "year to date") to explicit dates, and say which dates you used. Ask for the financial year end when the user says "this year" and it matters.

## Report the numbers faithfully

- Amounts are decimal strings in the report's `currency`. Quote them as returned and follow the `sign_convention` in each result; do not recompute totals or re-sign figures.
- Accounts with no movement or a zero balance are left out, so an account missing from the list means it is nil for that range.
- Lead with the few lines that explain the answer (largest movements, biggest balances, oldest debts) rather than reading out every account.

## Drill down

1. Take the account `id` from a report line.
2. `briefcase_list_journals` with `account_id` and the same date range shows that account's activity; its `debit`, `credit` and `totals` cover that account only.
3. `briefcase_get_journal` for one entry shows every line and `source_links`, such as `sales_invoice_id` or `transaction_id`. Follow them with `briefcase_get_sales_invoice` or `briefcase_get_transaction`.

For an aged report line, the invoice `source` tells you which tool opens it (`SALES_INVOICE` → `briefcase_get_sales_invoice`, `TRANSACTION` → `briefcase_get_transaction`).

## Limits

These reports read Briefcase's own ledger. There is no trial balance, VAT return or bank reconciliation tool; point the user to the Briefcase app for those. For how-to questions about the reports, use `briefcase_search_help` rather than guessing.

View saved version →

---
name: manual-journals
description: Post a manual journal to a Briefcase Ledger client, such as a correction, reclassification, capital introduction or one-off period-end adjustment, with the accounts checked, the lock date respected and a preview agreed before anything posts. Use when the user asks to post, book or record a journal, move a balance between accounts, or correct a posting.
---

# Manual journals in Briefcase

A posted journal changes the client's accounts immediately and can only be reversed in the Briefcase app. Treat every journal as irreversible from here. Manual journals only exist for Briefcase Ledger clients (Xero and QuickBooks clients return `UNSUPPORTED_CAPABILITY`) and need the Ledger post permission.

## Before drafting

- Check whether a journal is the right tool. Recurring prepayments, accruals, deferred income and depreciation belong in the close tools (see the financial close review skill), and a miscoded bill should be fixed on the transaction, not journalled over.
- `briefcase_get_client` gives `general_ledger_lock_date`. Entries must be dated after it.
- `briefcase_get_reference_data` with `kind: accounts` for account ids (narrow with `account_class`, for example `EXPENSE`, or `search_term`), and `kind: tax_rates` when a line carries VAT. Quote each account's name and code back to the user.
- To correct something already posted, read it first with `briefcase_list_journals` (filter by `account_id` and dates) and `briefcase_get_journal`.

## Draft and preview

Call `briefcase_create_manual_journal` with `mode: preview`:

- `entry_date`, `description` and a `reference` the user will recognise later.
- `lines`: each has an `account_id` and either a `debit` or a `credit` (never both), as gross amounts in major units. A `tax_rate_id` splits the VAT to the VAT account automatically; revenue and expense lines need one.
- `business_id` (and `property_id` with it) when the entry belongs to one business or property.

Show the user the lines as a small debit and credit table with the totals, then explain any blocker:

- `PERIOD_LOCKED`: the date is on or before the lock date. Move the date or ask the user to move the lock date in the app.
- `UNBALANCED`: debits and credits differ. Never add a balancing line the user did not ask for.
- `RESERVED_ACCOUNT`: control accounts such as accounts receivable and payable cannot take manual journals; the fix belongs on the invoice or bill.
- Deleted or unknown accounts, invalid lines, and accounts spanning businesses or properties.

## Post

Only after the user explicitly approves the preview, call again with `mode: execute`, the `preview_id` and a fresh `idempotency_key`. Return the `web_url`, then show the effect: `briefcase_get_balance_sheet` or `briefcase_get_profit_and_loss` for the affected period.

If a call fails with a network error, retry with the same `idempotency_key`; Briefcase will not post the journal twice. Never retry with a new key to get round an error.

View saved version →

---
name: sales-invoicing
description: Raise sales invoices for a Briefcase Ledger client from its sales items, create customers without duplicating existing contacts, list outstanding invoices, fetch invoice PDFs and build a debtor chase list. Use when the user asks to invoice a customer, add a customer, see what is unpaid or overdue, or get a copy of an invoice.
---

# Sales invoicing in Briefcase

Sales invoices only exist for Briefcase Ledger clients; Xero and QuickBooks clients return `UNSUPPORTED_CAPABILITY`. Reading invoices needs the Ledger view permission, raising invoices and adding customers need Ledger post. `FORBIDDEN` means the user lacks one of them or an administrator has paused assistant changes; report it and stop.

## See what is outstanding

- `briefcase_list_sales_invoices` with `statuses` (`AWAITING_PAYMENT`, `PAID`, `WRITTEN_OFF`, `PROCESSING`) and `search_term` for a customer or reference. Page with the cursor.
- `briefcase_get_sales_invoice` for lines, VAT, outstanding balance, payments and emails sent. For the PDF, call `briefcase_get_attachment_download` with `pdf.attachment_id`; the link is short-lived, so hand it straight to the user and do not repeat it later.
- For a chase list, use `briefcase_get_aged_report` with `subledger: ACCOUNTS_RECEIVABLE`: group by customer, oldest bucket first, with each invoice's reference, due date and outstanding amount.

## Raise an invoice

1. Find the customer with `briefcase_list_contacts`. If they do not exist, see "Add a customer" below.
2. Find the items with `briefcase_get_reference_data` and `kind: items`. Each item has a fixed price and VAT rate; the invoice uses the item's current price. If nothing fits, the user must add the item in the Briefcase app.
3. Call `briefcase_raise_sales_invoice` with `mode: preview`: `customer_id`, `issue_date`, optional `supply_date` (defaults to the issue date), `due_date`, `bank_account_id` for the bank details to print, and `lines` of `item_id` and `quantity`.
4. Show the preview: customer, dates, each line's net and VAT, and the totals. Explain any blocker in plain language. `PERIOD_LOCKED` means the issue date is on or before the lock date; missing issuer address, VAT number or customer address must be fixed in the app first.
5. Only after the user agrees, call again with `mode: execute`, the `preview_id` and a fresh `idempotency_key`. Return the invoice reference and `web_url`.

Say before executing that the invoice posts to the ledger straight away, is not emailed to the customer, and can only be reversed in the Briefcase app.

## Add a customer

1. `briefcase_create_customer` with `mode: preview`, the `name`, and optionally `email` and `address` (`region_code` is the two-letter country code, for example `GB`).
2. If the preview lists `candidates`, show them and ask whether the user meant one of those. Use the existing contact if so.
3. `resulting_action: REUSE_EXISTING` means a contact with exactly that name already exists and will be made a customer rather than duplicated.
4. Execute with a fresh `idempotency_key`. Pass `confirm_new_despite_candidates: true` only when the user has confirmed the new customer is different from every candidate.

## Retries

Retry a failed call with the same `idempotency_key`; Briefcase returns the original result instead of raising a second invoice. For how-to questions, use `briefcase_search_help`.

View saved version →

---
name: transaction-review
description: Review bills and receipts awaiting review in Briefcase for a client, explain Autopilot decisions and review warnings, fix extracted values, and publish or archive with a preview first. Use when the user asks what needs review, why a transaction was coded a certain way, or wants to approve or clear a client's queue.
---

# Transaction review in Briefcase

Work as the signed-in Briefcase user on the clients they connected. Never guess a client: resolve the name with `briefcase_list_clients` first and confirm when two names are close.

## Find what needs attention

1. `briefcase_get_connection` once per session to confirm which clients are visible and whether changes are allowed.
2. `briefcase_list_transactions` with `awaiting_review: true` for the client. Page with the returned cursor; do not ask for everything at once.
3. For each item the user cares about, `briefcase_get_transaction`. Explain the extracted values, the Autopilot reasoning and every review warning in plain language before proposing an action.

## Fix values

- Use `briefcase_get_reference_data` for accounts (narrow with `account_class` or `search_term`), tax rates, tracking categories, businesses and properties before changing a coding. Quote the exact account name and code back to the user.
- `briefcase_update_transaction` saves edits as metadata; it is last-write-wins, so read the transaction again before editing when the user has been working in the app.
- Never change amounts, dates or suppliers without the user's confirmation. Say what you will change and wait.

## Publish or archive

- Always call `briefcase_publish_transaction` or `briefcase_archive_transaction` with `mode: preview` first. Summarise the preview: ledger, account, tax treatment, period, and anything that blocks it (missing supplier, locked period, permission).
- Only after the user agrees, call again with `mode: execute`, the `preview_id` from the preview and a fresh `idempotency_key` (a random string you generate once per action).
- If the call fails with a network error, retry with the same `idempotency_key`; Briefcase replays the original result rather than posting twice.
- `FORBIDDEN` means the user lacks that permission in Briefcase or an administrator has paused assistant changes. Report it; do not look for another route.

## Follow up

Use `briefcase_get_operation` to check an action that returned `dispatched`. Point the user to Settings → AI assistants → Activity for the record of everything you changed.