Appearance
Plan: management reporting (profit and loss, key figures, cash forecast)
Status: plan, awaiting the Product Owner's approval; no code yet.
Why
An accountant who is paying attention tells the owner, every month: how the company did, where the money is, what is owed each way, what tax is coming, and whether cash will run short. FEAW's owner gets this once a year, with the accounts. GetMy Books already reads the pieces (bank lines, open invoices and bills, the VAT draft, the deadline radar). This plan puts them together into five read-only reports, delivered through Claude like every other tool.
It serves the vision ("watches the books ... surfaces savings") and SM-2 (cash collected sooner, a dividend taken safely). There is no capability for it yet: it needs a new one (see Decisions). It is not a dashboard of our own (docs/not-doing.md): every report is an MCP tool reply read in Claude.
House rules that shape every section:
- Money is integer pence, and every figure comes from pure code in
src/rules/(new filesprofit-and-loss.ts,key-figures.ts,cash-forecast.ts,recurring.ts,month-end.ts). No I/O there; "today" is passed in as a London date. - Code builds the words too. Each tool returns a code-built summary first (headline, tables in pounds, dates as
30 Sep 2026), then the full data asstructuredContent, through thesrc/present/layer from issue #96 (UI 1) and #97 (UI 2). Claude quotes it; it never adds, divides or rounds. - Entity from the session only, under RLS. Nothing here writes to Xero. The only thing stored is the owner's settings (cash buffer, recurring list).
1. Monthly profit and loss
What the owner sees
text
FEAW SERVICES LTD: profit and loss, September 2026 (accruals, from Xero)
Net profit £6,450.00, up £2,570.00 on August and £550.00 on September 2025.
Sep 2026 Aug 2026 Sep 2025 Year to date
(Apr-Sep 2026)
Sales £18,400.00 £15,250.00 £16,900.00 £97,300.00
Cost of sales £2,100.00 £1,950.00 £2,300.00 £12,400.00
Gross profit £16,300.00 £13,300.00 £14,600.00 £84,900.00
Overheads £9,850.00 £9,420.00 £8,700.00 £57,600.00
Net profit £6,450.00 £3,880.00 £5,900.00 £27,300.00
Largest changes on August: Sales +£3,150.00; Software +£380.00.
Accounting period 1 Apr 2026 to 31 Mar 2027: 6 of 12 months.
Warning: 4 Starling lines in September are not reconciled in Xero, so these
figures may be incomplete (see bank_reconciliation_check).(All figures synthetic.)
Data sources and Xero endpoints
GET /api.xro/2.0/Reports/ProfitAndLosswithfromDateandtoDate. The endpoint also takesperiods(1 to 12),timeframe(MONTH,QUARTER,YEAR),trackingCategoryID,standardLayoutandpaymentsOnly(cash basis). Response:ReportWithRows(sections, rows, cells; account cells carry the account ID as an attribute).GET /Organisation(accounting.settings.read, held): financial year end day and month, so year to date runs from the start of the accounting period.- Scope:
accounting.reports.profitandloss.read(new). Xero's generic OpenAPI file still lists the broadaccounting.reports.read, which is not available to apps created from 2 March 2026. This repo already requests the granularaccounting.reports.banksummary.read(src/xero/session.ts). One Xero reconnect per entity; do it in the same reconnect as SPEC-005 and SPEC-006 if the timing allows.
Reports API or journals: use the Reports API.
| Xero's ProfitAndLoss report | Built from journals | |
|---|---|---|
| Matches what the accountant and Xero show | Yes, by definition | Only if our code copies Xero's layout and rules |
| Access | Granular report scope, any tier | GET /Journals needs accounting.journals.read, the Advanced tier and a security assessment (ADR 0024) |
| Calls | One per column | Paged through every journal |
| Detail | Account totals only | Line level |
Journals are ruled out by the tier alone. When the owner asks "why did Software go up?", the tool drills into invoices, bills and bank transactions for that account and month (scopes already held), not into journals.
Method
- One call per column with explicit
fromDateandtoDate: this month, previous month, same month last year, year to date (4 calls). Notperiodsandtimeframe: Xero's comparison columns are reported to drop the 31st of the month from earlier periods when the base month has 30 days (Xero developer community; CData's documentation). - Parse rows into
{ accountId, name, section, pence }insrc/xero/, then pure code builds the table, the differences and the "largest changes" (top 3 by absolute change, from code). - Self-check: in code, the section rows must add up to Xero's own section totals and to Net Profit. If not, the tool refuses with a plain reason rather than showing a figure that does not tie.
- Accruals basis by default (what the accounts use); cash basis (
paymentsOnly=true) on request (see Decisions). - Warn when SPEC-003 finds unreconciled lines in the month.
Limits
- Xero's figures are only as good as the books: unreconciled lines, uncoded receipts and missing bills make the month wrong. The warning says so.
- Year-to-date and same-month-last-year ranges: Xero's docs are reported to require
fromDatewithin a year oftoDate. Both ranges fit; to confirm there is no "within a year of today" limit for last year's month. - No budgets or targets in this slice.
2. Balance sheet snapshot and key figures
What the owner sees
text
FEAW SERVICES LTD: key figures at 30 Sep 2026
Cash after what is owed (before customers pay): £1,282.95
Cash at bank Starling £24,310.55 (bank balance; Xero shows £23,980.10,
difference is 4 unreconciled lines)
Amex card £1,842.20 owed, due 9 Oct 2026
Owed to us £21,640.00 from 7 customers, £5,200.00 overdue
Owed by us £3,915.40 on 5 bills, none overdue
VAT £5,400.00 for Jun-Aug, due 7 Oct 2026
£3,120.00 so far for Sep-Nov (cash accounting)
PAYE and NI £1,850.00, due 22 Oct 2026
Corporation Tax £6,900.00 to set aside (estimate, see owner-director-money)
Balance sheet (Xero): net assets £48,700.00; retained profits £41,200.00."Cash after what is owed" is Starling, less the card, bills, VAT, PAYE and Corporation Tax. Debtors are shown but not counted.
Data sources and Xero endpoints
| Figure | Source | Scope |
|---|---|---|
| Cash | Starling balance (existing read-only token); Xero Reports/BankSummary closing balance per account | held |
| Amex | Latest statement file balance and due date (statements/, SPEC-003) | none |
| Owed to us, by us | payments_aged (SPEC-006, src/rules/aged-balances.ts) | held |
| VAT | SPEC-001 derivation (src/vat/derive-return.ts, cash scheme) for the last unpaid quarter and the quarter so far | held |
| PAYE and NI | Balance of the PAYE liability account on the balance sheet | new |
| Corporation Tax | The estimate from docs/plans/owner-director-money.md; until it exists, Xero's Corporation Tax liability balance, labelled as such | new |
| Net assets, retained profits | GET /Reports/BalanceSheet?date= (also periods, timeframe, paymentsOnly) | accounting.reports.balancesheet.read (new; spelling to confirm) |
Accounts are identified by account ID and type from GET /Accounts (held), never by the label in the report. The PAYE account is not a Xero system account, so the owner confirms which account it is once; the choice is stored per entity.
Method
Pure keyFigures(inputs, today) in src/rules/key-figures.ts: takes each figure already in pence and returns the lines and the "cash after what is owed" total. Nothing is fetched twice: payments_aged and the VAT draft are called as functions, not re-implemented.
Limits
- Starling's balance includes Spaces only if the feed does (QD-10).
- VAT so far this quarter assumes nothing else is received or paid before the quarter ends; the forecast (section 3) covers the rest.
- PAYE is whatever Xero holds: we do not run payroll (
docs/not-doing.md). - The Corporation Tax figure is an estimate owned by the other plan.
3. Cash-flow forecast, 13 weeks
What the owner sees
text
FEAW SERVICES LTD: cash forecast, 13 weeks from 28 Sep 2026
Lowest point £9,480.30 in the week of 14 Dec 2026. Your buffer is £5,000.00:
the forecast stays above it throughout.
Week of Money in Money out Closing What drives it
28 Sep £2,400.00 £1,210.00 £25,500.55 Opening £24,310.55; subscriptions
5 Oct £6,000.00 £7,242.20 £24,258.35 VAT £5,400.00 (7 Oct); Amex £1,842.20
12 Oct £3,500.00 £2,915.40 £24,842.95 Bills from 3 suppliers
19 Oct £0.00 £7,550.00 £17,292.95 PAYE £1,850.00; salaries £4,200.00; rent £1,500.00
... (weeks 5 to 11 in the full reply)
14 Dec ... ... £9,480.30 Lowest point
21 Dec ... ... £11,905.30
Not included: sales not yet invoiced, bills not yet in Xero, the Sep-Nov VAT
return (due 7 Jan 2027, after the horizon).Data sources
- Opening cash: Starling balance today (the bank, not Xero), the same figure as key figures. Amex is not cash: its statement balance is a payment on its due date.
- Receipts: open sales invoices (
payments_aged), less unallocated credit. - Payments: open bills (
payments_aged). - Tax: dates from the deadline radar (
src/rules/deadlines.ts); amounts from key figures and the VAT derivation. - Payment history: paid sales invoices for the last 12 months (
GET /InvoiceswithStatuses=PAID, paged;FullyPaidOnDate; held scope). - Bank history: 6 months of Starling lines (SPEC-003 sources).
Method
All in pure src/rules/cash-forecast.ts and src/rules/recurring.ts. Weeks run Monday to Sunday, London dates, week 1 is the current week.
- Receipts. Each open invoice lands on its due date plus that customer's median days late over the last 12 months (at least 3 paid invoices; otherwise the company median; otherwise the due date). An already-overdue invoice lands on today plus the lateness still expected, never in the past. Invoices over 90 days overdue are left out and listed as "at risk". Foreign-currency invoices use their pound value (SPEC-006 S13).
- Payments. Each open bill on its due date; overdue bills in week 1. No lateness assumed (prudent).
- Tax.
- VAT: the unpaid return's figure on its due date (1 month and 7 days after the quarter). For a quarter still open, the draft so far plus the VAT inside forecast receipts and payments before quarter end (cash accounting: VAT follows the money).
- PAYE and NI: the PAYE account balance on the next 22nd, then the average of the last 3 PAYE payments seen in the bank on each later 22nd. Placed on the last working day on or before the 22nd (the weekend rule is to confirm with HMRC's guidance).
- Corporation Tax: 9 months and 1 day after the period end, from the other plan's estimate, if inside the horizon.
- Recurring costs. From bank history, group lines by normalised payee (
payeeKeyinsrc/rules/outstanding.ts). A group is recurring when it has at least 3 payments at a steady interval (weekly, monthly, quarterly, within 3 days) and amounts within 10% of each other. It is projected forward at the latest amount. Payees that already have an open bill, and HMRC, are skipped so nothing counts twice. Salaries are detected the same way from net pay lines. The owner confirms the list once (stored per entity); new candidates are shown, not added, until confirmed. - Roll forward. Opening plus in, less out, week by week; the lowest closing balance and its week; each week's biggest drivers named.
Limits
- It is arithmetic on what is already known, not a prediction. Sales not yet invoiced, one-off costs and bills not yet entered are missing, so the forecast gets less complete further out. The reply says so every time.
- Lateness uses history; a customer who changes habits breaks it.
- Recurring detection misses irregular costs and annual ones with fewer than 3 years of history.
- VAT and Corporation Tax amounts are estimates until the return or the computation is final.
- No interest, no foreign exchange movement, no Amex spending beyond the current statement.
4. "Can I afford this?"
What the owner sees
text
A £6,000.00 dividend on 9 Oct 2026
Lowest point falls from £9,480.30 to £3,480.30 (week of 14 Dec), which is
£1,519.70 below your £5,000.00 buffer.
Retained profits in Xero are £41,200.00, so the dividend is within
distributable profits on the last balance sheet (Companies Act 2006, s830).
Tax on the dividend for you personally: see owner-director-money.Method
Pure whatIf(forecast, change): adds one outflow (purchase or dividend, amount in pence, date) to the forecast and re-runs the roll-forward. For a purchase with VAT, the VAT is taken off the next VAT payment if that falls inside the horizon (cash accounting: reclaimed in the quarter it is paid). It returns the old and new lowest point, the first week below the buffer, and the first week overdrawn, if any. For a dividend, it also compares the amount with retained profits from the balance sheet, and says it is only a check against the last figures, not advice.
Limits
Same as the forecast. Retained profits in Xero are not the same as distributable profits once the accounts are adjusted; the reply says so. Nothing is saved and nothing is paid.
5. Month-end check
What the owner sees
text
FEAW SERVICES LTD: month-end check, September 2026
3 of 5 checks pass. 2 need you.
[x] Starling reconciled to 30 Sep: 4 lines open (press OK on 3, enter 1)
[ok] Amex statement to 12 Sep reconciled
[ok] VAT: Sep-Nov so far £3,120.00; no unmapped tax codes
[x] Overdue: 2 customers owe £5,200.00 over 30 days (chase list ready)
[ok] Deadlines: VAT return due 7 Oct 2026 (7 days); PAYE due 22 Oct 2026
Profit for September £6,450.00; forecast lowest point £9,480.30.Method
Pure monthEnd(results) composes results the other tools already build: SPEC-003 bank_reconciliation_check per account, the SPEC-001 draft and its unmapped tax types, payments_aged overdue totals, deadlines_upcoming for the next 30 days, and the headline figures from sections 1 and 3. One summary, each line pass or needs you, with the tool to run next.
Limits
It checks, it does not fix. A month is "reconciled" only when every line to the month end is matched in Xero (SPEC-003's definition).
MCP tools sketch
All read-only (readOnlyHint: true), except the settings tool, which writes our own database only, never Xero.
| Tool | Returns |
|---|---|
reports_profit_and_loss | Month, previous month, same month last year, year to date; largest changes; reconciliation warning |
reports_key_figures | Cash, card, debtors, creditors, VAT, PAYE, Corporation Tax, cash after what is owed, net assets |
forecast_cash | 13 weekly rows, lowest point, buffer check, what is left out |
forecast_what_if | Before and after lowest point for one purchase or dividend |
month_end_check | The checklist and one headline |
reporting_settings | Show or set the cash buffer, the PAYE account and the confirmed recurring list |
The input never carries an entity ID the server trusts; the entity comes from the session (CLAUDE.md rule 4).
Slices
Ordered by value. Each is small and ends with its own exit test.
- Monthly P&L and key figures.
reports_profit_and_loss,reports_key_figures, the two new report scopes and one reconnect. Recommended first: it answers "how are we doing?" and ties to Xero. - Month-end check. Composes tools that exist; small.
- Forecast v1. Opening cash, invoices and bills by due date, tax dates. No lateness, no recurring costs.
- Forecast v2. Customer lateness and recurring costs, with the confirmed recurring list.
- Can I afford this?
forecast_what_ifand the cash buffer setting.
Acceptance tests
- P&L to the penny. Given FEAW's books, when
reports_profit_and_lossruns for September 2026, then every account line and the P&L totals equal Xero's Profit and Loss report for the same period to the penny. - Columns. Given synthetic Xero reports for Sep 2026 (net profit £6,450.00), Aug 2026 (£3,880.00) and Sep 2025 (£5,900.00), when the tool runs, then the headline reads "up £2,570.00 on August and £550.00 on September 2025", and the text holds no pence values.
- Totals that do not tie are refused. Given a report whose rows sum to £1.00 more than its Net Profit, when the tool runs, then it refuses with a plain reason and shows no figures.
- 30-day month. Given a sale dated 31 Aug 2026, when the P&L runs for September 2026, then August includes that sale.
- Key figures. Given Starling £24,310.55, Amex £1,842.20, bills £3,915.40, VAT £5,400.00 and £3,120.00, PAYE £1,850.00 and Corporation Tax £6,900.00, when
reports_key_figuresruns, then cash after what is owed is £1,282.95. - Lateness. Given Acme's last 4 invoices were paid 5, 9, 9 and 14 days late, and an open Acme invoice of £6,000.00 due 1 Oct 2026, when
forecast_cashruns on 30 Sep 2026, then the £6,000.00 lands on 10 Oct 2026, in the week of 5 Oct. - Tax dates. Given a Jun-Aug VAT return of £5,400.00 and a PAYE balance of £1,850.00, when the forecast runs on 30 Sep 2026, then £5,400.00 goes out on 7 Oct 2026 and £1,850.00 on 22 Oct 2026; and a PAYE payment due on Sunday 22 Nov 2026 is placed on Friday 20 Nov 2026.
- Recurring, never twice. Given 4 monthly payments of £1,500.00 to "LANDLORD LTD" on the 1st, and no open bill from them, when the forecast runs, then £1,500.00 is projected on each 1st; given an open bill from the same payee for that month, then only the bill is counted.
- Lowest point and buffer. Given the synthetic forecast above and a buffer of £5,000.00, when a £6,000.00 dividend on 9 Oct 2026 is tested, then the lowest point is £3,480.30 in the week of 14 Dec 2026 and the reply says it is £1,519.70 below the buffer.
- Purchase with VAT. Given a £2,400.00 purchase including £400.00 VAT on 12 Oct 2026, and no VAT payment inside the horizon after that date, when tested, then the lowest point falls by £2,400.00.
- Month-end. Given 4 open Starling lines to 30 Sep and £5,200.00 over 30 days overdue, when
month_end_checkruns, then it shows 2 checks that need the owner, each naming the tool to run next. - Isolation and read-only. Given a session for FEAW only, when any tool here asks for WealthTechPros, then nothing is returned; and no tool here calls a Xero write endpoint (checked in a unit test on the client).
- Pure and whole. Every function in the new
src/rules/files takes and returns whole pence; a unit test feeds fractional input and expects a thrown error. The new files join the 80% per-file coverage floor.
Decisions for the Product Owner
| Ref | Decision | Recommendation |
|---|---|---|
| new | Add a capability for management reporting (for example CAP-03.3 under Advise, MVP or post-MVP) | Add it as CAP-03.3, MVP, with slice 1 in the build order after SPEC-006 |
| new | Minimum cash buffer | The owner sets it; default suggestion £5,000.00 or one month of fixed costs, whichever is higher |
| new | Forecast horizon | 13 weeks, weekly; not longer, since it would rest mostly on guesses |
| new | P&L basis | Accruals (as the accounts), cash basis on request |
| new | Opening cash from the bank or from Xero | The bank (Starling), with Xero's figure and the difference shown |
| new | Store the confirmed recurring list and PAYE account per entity | Yes, a small table under RLS; nothing else stored |
| new | Scopes accounting.reports.profitandloss.read and accounting.reports.balancesheet.read, one reconnect | Yes, in the same reconnect as SPEC-005 and SPEC-006 |
| new | Dividend check against retained profits | Show it as a check with the s830 citation, clearly not advice |
Sources
Checked 2026-09-30.
- Xero Accounting API OpenAPI file (ProfitAndLoss, BalanceSheet, BankSummary parameters; Journals scope): https://raw.githubusercontent.com/XeroAPI/Xero-OpenAPI/master/xero_accounting.yaml
- Xero reports documentation (did not render for the automated check): https://developer.xero.com/documentation/api/accounting/reports
- Xero Granular Scopes FAQ (2 March 2026; September 2027 for older apps): https://developer.xero.com/faq/granular-scopes
- Apideck, "Xero Scopes: What Changed" (granular report scope names): https://www.apideck.com/blog/xero-scopes
- Codat, Xero scopes by use case (spells the balance sheet scope
balancesheets, hence "to confirm"): https://docs.codat.io/integrations/accounting/xero/partner-certification/scopes/ - Xero scopes page (did not render): https://developer.xero.com/documentation/guides/oauth2/scopes/
- Xero API limits (did not render; figures from search summaries: 5 concurrent, 60 a minute and 5,000 a day per organisation, 10,000 a minute per app; headers
X-MinLimit-Remaining,X-DayLimit-Remaining,X-AppMinLimit-Remaining; 429 with Retry-After): https://developer.xero.com/documentation/guides/oauth2/limits/ - CData, ProfitAndLoss (date limits, 30/31-day comparison issue): https://cdn.cdata.com/help/DXJ/powerbi/pg_accountingtable-profitandloss.htm
- ADR 0024 (journals need the Advanced tier):
docs/decisions/0024-xero-connection-limits.md - GOV.UK, Pay employers' PAYE (22nd of the next tax month): https://www.gov.uk/pay-paye-tax
- Companies Act 2006, section 830: https://www.legislation.gov.uk/ukpga/2006/46/section/830
A forecast run makes about 10 Xero calls plus paged invoice reads per entity, well inside those limits.