The R 100 000 "Maintenance" section never had a home. On the workbook's Cost
sheet it is cell I97 — an orphaned figure with no section header above it and
no breakdown under it, sitting inside the sheet's own grand total of
R 1 110 486,87. Round 3 gave it a section, a card, a page and a sidebar entry
(7194e78). It was never a cost: nothing was ever attached to it.
The client ruled on 2026-11-05 that the app works from LIVE data and the
workbook is only history. So Maintenance comes out completely:
- the live PocketBase row (section "Maintenance", R 100 000) is deleted
- the seed row is removed from data/source/overheads.json, so a re-seed
cannot bring it back
- the card entry, the /expenses/maintenance page and the sidebar link
are removed
- data/source/overheads-extra.json — a DEAD file nothing imported (zero
references anywhere in the repo; the seed reads overheads.json
explicitly and only globs invoice-*.json) holding the round-2
Insurance/Tracking sections plus a mislabelled duplicate
"{ section: Cash Floats, description: Maintenance, incl: 100000 }" —
is trashed
Both pages now read the same money: /expenses and /overheads both show
R 580 485,37, over 6 categories and 25 lines. The vehicle/overhead split
under the headline is R 143 326,36 tied to a vehicle and R 437 159,01
company overheads.
The reconciliation against the workbook gains a third itemised delta, and it
is a SUBTRACTION this time, because the workbook's grand total still counts
the orphan cell:
R 1 110 486,87 workbook grand total (Cost sheet row 98)
- R 415 523,94 machine instalments — they live on each asset
- R 19 800,00 the workbook's own Personnel total is R 19 800 too high
+ R 5 322,44 Santam — the app keeps it, the workbook's subtotal skips it
- R 100 000,00 Maintenance — an orphan cell, removed from the app
= R 580 485,37 the roll-up
scripts/verify-cost-reconciliation.mjs now carries KNOWN_MAINTENANCE_REMOVED
and still exits 0 with R 0.00 unexplained. The note on /overheads is
generated from the constants, never typed, so it cannot drift. The three
signs matter: Personnel comes OFF, Santam goes back ON, Maintenance comes OFF.
AGENTS.md records the live-data ruling and renames the section heading from
"the cards are built FROM the sheet" to "FROM THE ROWS", since the sheet is
history and the rows are the truth.
The Subscriptions VAT errors (Charl - CCS, Buildsmart Yearly update) are
untouched — still flagged, still failing the seed loudly, still the client's
to fix.
Verified: typecheck clean; 162 tests (156 pass, 0 fail, 6 skipped);
production build clean and /expenses/maintenance gone from the route list;
reconciliation exits 0 with R 0.00 unexplained; /expenses and /overheads
both read R 580 485,37 at 375x812 with no overflow and no dead links.
The Expenses Overview had three cards pointing at routes that were never created
("Plant Overheads", "Insurance", "Tracking" were GL-account labels living inside
"Vehicle Costs" and "Bastion Finance", not section names). Each showed R 0 and
404'd, while three real sections had no card at all, and the headline read
R 437 159,01 against a stored R 680 485,37 - the R 243 326,36 the 2026-11-04
audit flagged as omitted (EX-01, EX-02).
The card list is now built FROM the overhead rows (lib/expenses-sections.ts), not
from a hand-written array of section names. A hard-coded list is what caused the
bug: the next section added to the sheet would be dropped the same way. A
section with no catalogue entry still gets a card, flagged, and still counts
toward the total - so a category can never vanish again. lib/expenses-sections.test.ts
reads data/source/overheads.json directly rather than a hand-typed fixture, so
it cannot drift by a cent, and asserts the total equals the sum of every row.
The cards are in TWO groups, because the money is not the same money:
Running cost - tied to a vehicle R 143 326,36
Vehicle Costs, Bastion Finance
Overheads - not tied to a vehicle R 537 159,01
Personnel, Maintenance, Rent & Utilities, Cash Floats, Subscriptions
Total monthly overhead R 680 485,37
The vehicle sections are the SAME money the per-vehicle registers on /running
already show - TLB06 R 29 036,08 is the Bastion finance row, DT01 R 1 033,29 and
WB02 R 3 318,14 are the Vehicle Costs rows - so those two cards carry an "Also
shown on Running Costs - do not add the two" note, and the split is printed
under the headline. The grand total is the sum of every overhead row, so /expenses
and /overheads now agree to the rand.
Also:
- /expenses/maintenance is new (the R 100 000 section had no page anywhere),
built on the same ExpenseSectionPage as its siblings.
- Purchase orders sit OUTSIDE the overhead total on purpose: a PO becomes
running cost when it lands on a machine. The strip reads the same loader as
the Suppliers page (lib/supplier-spend-data.ts) over the same default view,
so the two screens quote identical rands.
- /expenses/petty-cash now shows the R 10 000 monthly float allocation, so the
hub card and the page cannot disagree.
- The /overheads reconciliation note is generated from OVERHEAD_RECONCILIATION
instead of being typed. It quoted R 689 640,49, which reconciles with neither
the workbook nor the app. The real arithmetic is R 1 110 486,87 - R 415 523,94
(plant instalments, they live on each asset) - R 19 800,00 (the workbook's own
Personnel total is too high) + R 5 322,44 (Santam: the app keeps it, the
workbook subtotal skips it) = R 680 485,37.
- Maintenance is in the sidebar - every other expense section page is.
Vehicle Costs and Bastion Finance stay OUT of the sidebar: Running Costs
already covers them. The hub cards still link to their pages.
The Subscriptions VAT rows are still broken and npm run seed still exits
non-zero on them. Flagged, not quietly fixed.
Verified: typecheck clean, 162 tests (156 pass, 0 fail, 6 skipped), production
build clean, mobile checklist at 375x812 and 768x1024 on /expenses,
/expenses/maintenance, /expenses/petty-cash, /expenses/suppliers-2 and
/overheads - no horizontal scroll, no text under 12px, no tap target under
44x44.
TLB06 was paid off in October 2026, but the running-cost rule dropped a SETTLED
agreement from EVERY month, so the ten instalments it was really paying
(January-October, R290 360,80) vanished from the year to date.
An agreement is now charged for the months it was live, and its paid-off date
decides when the money stopped:
- LIVE: from its start through its paid-off date, or through the current month
when no paid-off date is on record.
- SETTLED: up to its paid-off date - those instalments really were paid - and
nothing at all when there is no paid-off date, because there is then no month
we can say it paid for. "Settled" means paid off, or will be paid off by
that date, so a settled agreement whose date is still ahead is still charged.
TLB06 is charged January-October and NOT November. Nothing else moves: every
other agreement's window already ran to November or beyond.
- Overview YTD R6 241 894,70 -> R6 532 255,50. The November figure is
unchanged at R441 493,12.
- Financing register YTD instalments R4 395 038,56 -> R4 685 399,36, and
"Committed for November" stays R399 548,96.
The Overview and the register still read ONE rule, so their finance year to
date is the same figure - asserted in lib/running-month.test.ts, together with
the TLB06 case and the live-agreement cases.
committedMonthly() in lib/financing.ts was never called and stated the old
rule, so it is gone rather than left lying next to the real one.
The client asked for two things on the running-cost pages: drop the two prose
notes, and show the year-to-date figure next to the total for the current month.
- /running loses the "Shown to Jan, Feb..." and "A re-cut of costs..."
paragraphs. The tiles carry the year and the month instead.
- /running shows "Nov so far" beside "YTD running cost", and the "made of"
line is printed for the month as well as for the year, so the month's total
is explained on the page and not only in the grid.
- The cards follow the income cards: YTD spend | Nov so far side by side from
md, the month on its own line below md, and the sparkline yields its width
below xl so the vehicle NAME is never truncated to pay for a decorative
trend. Below sm the name wraps instead of being cut short.
- /running/insurance shows the premium in force this month, and its
year-to-date figure now stops at the months that have happened. December is
a rate on file, not money spent, so including it made this page a full year
while the Overview showed eleven months - the same cost kind reading as two
different numbers on two screens.
- /running/financing shows "Committed for Nov" beside a new year-to-date
instalment figure.
One rule, three screens. elapsedMonths() in lib/income-month.ts counts the
months that have happened and is the same clock the income pages use, and
financeByAsset() / fleetFinanceByMonth() in lib/running-costs.ts are the only
finance rule the Overview and the financing register both read. The Overview's
insurance and finance year-to-date figures now equal the insurance and
financing pages' figures exactly.
lib/running-month.test.ts asserts it, including the insurance cross-check
between the register and the Overview.
A settled agreement still contributes nothing to any month - the instalments
TLB06 was paying in January-October are not in the Overview's finance figure.
The client confirmed the financing is correct as it stands, so that is left
alone and recorded in AGENTS.md rather than quietly changed.
The four kinds under running cost - repairs & parts, purchases, insurance
and finance - ARE the whole of a vehicle's running cost. That was true of
the arithmetic but not of the screen: a card showed one number with no
visible parts, and the only breakdown was a hover tooltip on the grid's
total row.
- Each card now shows its four parts, so what the vehicle's spend is made
of is visible without expanding it. A vehicle with no spend shows
nothing: "nothing recorded" is already on the card.
- The expanded panel shows the four parts against the vehicle's total.
- The grid's footer shows the fleet's four parts above the fleet total, so
a month column adds up on the screen instead of on trust.
- The page header states the fleet's four parts and the total side by side.
The parts ARE the spend and there is no fifth source, so the parts and the
total can never disagree. Any change that touches a cost kind must keep
that additivity true.
Also: the labels on this page were text-[10px], under the 12px floor the
mobile checklist sets. They are now 12px.
Two rulings recorded in AGENTS.md:
- FUEL IS NOT A PLANT RUNNING COST. The sites are invoiced for the fuel
they use. The only fuel that is a plant cost is the fuel a plant vehicle
takes from the tank for plant work, so a fuel log is never a running-cost
source however many litres it records.
- Only what is under running cost as it stands. The workbook's per-vehicle
fixed cost also carries depreciation/ownership and an operator
allocation; that is capital recovery and overhead, not running cost, so
it stays out - and the vehicles it covers (the excavator, the site and
office containers, the generators, the trailers) correctly show no
running cost on the Overview.
Two changes to the income overview, sharing one rule for what "the month"
means (lib/income-month.ts).
POSTED INCOME PER SITE
/income gains Vehicles / Sites views, and /sites defaults to the SAME
posted-income view with a separate Internal billed invoices view.
buildSiteIncomeRows (lib/site-income.ts) is the shared calculation: actual
monthly_income supplies the amount, year and month, and the linked invoice
supplies its historical site. It never uses assets.site, fuel-log
locations or today's map assignment.
- Unposted invoice lines are billing, not posted income.
- Historical workbook income with no site evidence stays in Unallocated
historical income; external income, whose site field names the SUPPLIER,
stays in Unallocated external income.
- Missing source references stay visible as unallocated invoice income.
No group is dropped to make a site list look cleaner and no site is
guessed to force a total.
- No site profit is calculated without an explicit cost-allocation rule.
- Invoice writes use revalidateInvoicePages, which invalidates both
registers, Income, Sites/details, Charts and Dashboard.
THE LIVE MONTH
The tiles show the year-to-date income and profit AND the current month,
and every vehicle card shows the current month income beside its year
figure.
- The month is the live CALENDAR month and it is shown even at R0. Income
for a month is usually entered near the end of it, so the current month
is a figure that starts at R0 and grows.
- The month index is computed on the SERVER and passed down as a number.
The browser never works it out for itself: two clocks disagreeing would
show two different months on the same page.
- A month profit is a dash until that month costs are posted. September
and October carry invoice income with no posted fixed costs (their costs
exist only as forecast rows), so a profit there would be income minus
zero - a 100% margin that does not tie back to the year-to-date profit.
It becomes a number by itself the moment the workbook posts that month.
- The 12-month strip shows the live month as R0 rather than a dash, so a
card cannot contradict itself. Months after it stay a dash.
- The sparkline on a collapsed card is hidden below xl: the content column
is only ~700px wide between md and xl, and the vehicle name must not be
truncated to pay for a decorative trend.
/plant and /plant/map import Fuel Logs CSVs by exact QR and show each
vehicle's current and previous distinct site with the dates they were
observed.
- plant_site_observations is durable, QR-keyed history. It is never wiped
and a previous site is never manufactured.
- An older or repeated snapshot must not move a vehicle backwards; untimed
conflicting sites on one day are held for review.
- A manual site change shares the same history and the same lock.
- Current/previous metadata and the sticker QR are captured BEFORE the asset
rows are deleted in the seed, so a re-seed cannot wipe them. Explicit
empty values are preserved too: clearing a site is a deliberate manual
observation, not permission to restore an old sheet value.
- Imports change location metadata only. They never touch income, cost or
fuel measurements.
- A new named site is created only for a matched Plant vehicle. Missing
coordinates mean "awaiting a pin", never a headquarters fallback.
Owner-confirmed 2026-11-04: TLB06's QR is 1089, not the old meter reading
4704. lib/plant-site-policy.json holds the confirmed aliases (Equestria
Bastion Job -> Equestria 215, Cosmo City / Lion Park -> Cosmo City); no
other identity is guessed.
An invoice saved with no amount landed as amount_incl = 0 (PocketBase
stores a number field as zero, not null), so the PO read "R 0,00 invoiced"
and the money never booked. There were two ways to give it an amount and
neither worked: the Upload-invoice modal let a blank amount save silently,
while the double-click correction form refused to save without a value AND
a written reason, and sat behind Edit mode.
- lib/purchase-invoice-amount.ts holds the rules, shared by the screen and
the API so they cannot disagree. R0 is not an amount: a blank amount and
a figure of zero are both refused, so an invoice can never land as zero.
- The API now separates PRICING an invoice that never had an amount (no
reason owed, still logged) from CORRECTING one that was booked (Full user
+ a reason, as before).
- Double-clicking an amount on a PO opens the ordinary invoice modal on
that invoice, with the amount field waiting. The inline correction form is
gone — one window, one rule. There is no pencil button: a booked figure
must take a deliberate second gesture, so a single stray tap never opens
a form that can rewrite money.
- The PO-lines table freezes its Description column with an opaque
background and fades its right edge, so it passes the mobile checklist.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Menu: old Suppliers leaf hidden (route kept), Suppliers 2 renamed Suppliers
- PO invoice status: new 'over' state (never closed), live over-PO warning when typing
- Admin correction of invoice amount/date/number with mandatory reason, logged to purchase_invoice_edits
- Payable now carries unpaid balance forward month to month
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- Supplier invoices on purchase orders (several per PO), global Upload invoice with search and drag-drop
- PO invoice status line (red/orange/teal), week/month filter, group by supplier, drag-drop PO upload
- Suppliers 2: spend, payable by terms, cash hidden by default, manual payments with surplus/shortfall
- Fix multi-page PO parsing (per-page rows, header filter direction)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- /expenses/suppliers: terms (cash / 30 / 60 days), PO + petty cash totals per supplier,
period filters, add/edit/delete, due dates
- POs and slips resolve to a supplier by code then folded name; new PO suppliers start
with terms unset, new slip suppliers as cash
- Full-user guard on cash-float and job-card write routes
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- Job cards scanner: oil QR books litres + vehicle (no odo/photo), bundled onto the
vehicle's job card (open job now, or the next job started the same day)
- Fuel tab is diesel only; /api/clock/oil-out added
- Users: Full / Clock-in user / Mechanic; mechanics see only Fuel + Job cards
- Plant Register: QR code column (double-click to set), kept across re-seeds and
used when matching scans
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- Plant Clock "Job cards" tab: scan a vehicle QR to start a job, scan again to finish
with odometer (or no meter), kind of work and a note
- /running/job-cards table with period, work, vehicle and mechanic filters
- Remove /running/operators and /running/mechanics; mechanic badge PDF moves to Employees
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- Scanning a vehicle QR (its register code, e.g. TLB04) books diesel from the main
tank; litres, optional odometer and a required meter photo (stored protected,
viewable from the Booked out table)
- Settings: users are Full or Clock-app-only; clock-only users are confined to /clock
- Clock app: tapped tab highlights at once plus a loading screen; remove the
"scanned on this device" list
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Insurance and finance genuinely recur, so left to fill all twelve months they made
November and December look known — ~R470k a month of phantom figures for months that
have not started, which is the "it will confuse the people" case exactly.
Both halves of the fix are needed:
- machineRunningCosts() caps every source at the horizon, so no phantom figure is even
computed. YTD is therefore genuinely year-to-date and moves as the year goes on.
- RunningView renders only that many columns. Future months are NOT rendered empty:
an empty column still reads as "we have a figure of zero", which is the same
confusion in a quieter form.
October is shown and is expected to grow as repairs and purchases land against a
vehicle. A PO dated beyond the horizon is skipped silently, which is not the same as
an undated PO — only a genuinely unreadable date is reported.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A machine with no repairs and no purchase order still carries an insurance premium
and, while it is financed, a monthly instalment. So a blank row was never "this
vehicle costs nothing" — it was "nothing recorded", which is a gap rather than a
figure. The Overview now totals all four kinds per machine per month.
Everything is read from POCKETBASE, the registers the client maintains in the app.
The original spreadsheet only bootstrapped the page (monthly_running_costs, Jan-Aug);
it is not a source here. September having no workbook data is expected and correct —
the figures there now come from the app.
Two finance sources existed and OVERLAPPED. The cost_lines instalment rows are the old
workbook's subset (5 machines, R115 576,14/mo); financing_terms is the client's current
sheet (18 agreements, R428 585,04/mo). Using both double-counted MG02, RV04, TLB06 and
TLB07, so financing_terms wins and the stale rows are ignored. TB01 has no financing_terms
row, so its old instalment no longer counts — consistent with it being absent from the
current sheet. Insurance has one source and no such problem.
Insurance is resolved from the RATE PERIODS rather than the derived cost_lines, so a
premium that moves mid-year is charged at the price that applied that month.
Also: settled agreements contribute nothing (a paid-off machine is not a running cost),
purchase lines are filed under the PO date, and the bottom row keeps showing incl above
excl. The page carries one line saying this is a re-cut of costs already inside fixed
expenses — adding it to them would count the same premium twice.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A purchase order buys parts and repairs against a plant item, so its money is
running cost and belongs in the same per-machine, per-month series the Overview
already reads. Without it September showed nothing at all.
Merged at READ time, never copied into monthly_running_costs: that collection is
deleted and rebuilt by every seed, so a purchase written there would vanish on the
next one and have to be re-uploaded. purchase_lines is never deleted, so the money
lives in one place and the Overview adds it up.
- Month comes from the PO date (when it was ordered), not "Required By":
MEGPPO50532 is dated 07/10 but required 29/08 and those must not be confused.
- Only lines allocated to a machine are counted. An unallocated line is real money
not yet on a plant item; it stays on /purchases, reported, rather than being
hidden or added to the fleet total.
- A PO with no readable date is excluded and named, never guessed into January.
- Bottom total row shows incl ABOVE excl per month and for the YTD. Workbook
figures carry no VAT column, so RUNNING_VAT_PCT (15, confirmed by every PO line)
is the single constant to revisit if they are ever restated ex-VAT.
September now reads R 5 842 incl / R 5 080 excl from the two September POs.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Splits the Running Costs group into six purpose-built pages, each with its own
collection and its own source data, plus a coordinate parser for purchase orders.
Insurance (R503 330/yr, 20 vehicles)
A premium can move every month or three, so it is stored as a RATE PERIOD in
insurance_rates and each month's cost is resolved against the rate in force
that month. cost_lines insurance rows are derived from those periods. An absent
rate is null, never 0 — nobody has entered the date, which is not the same as
being insured for free.
Financing (20 agreements, R428 585/mo)
Instalment from the sheet; start date, paid-off date and the settled toggle are
human-entered and preserved across re-seeds. Months-left and outstanding are
null until a date is entered, never R0 on a live debt. The two paid-off
agreements (WB02, DT01) show as settled and are excluded from the run-rate.
Purchases + Oil Stock
Uploads PO PDFs the way /income/invoices does. The parser reads columns by
x-position, because plain text extraction reorders them, and refuses any PO
whose lines do not sum to the sub-total. A cost code either names a machine
("SS-02" -> SS02) or a stock store ("MPLANT, ENGOIL") — never both, never
guessed. Oil POs move litres into oil_stock_movements instead of onto a machine;
stock is the sum of movements so the first usage is a subtraction from history.
Operators (19) and Mechanics (2)
Both are people with an employee number, separately reconcilable by the seed so
someone added in the app survives. Mechanics get a badge QR; a mechanic with no
employee number cannot be printed, because the code is what the QR encodes.
Cross-cutting
- The seed no longer deletes operators, mechanics or oil items: people are added
in the app, and those rows exist in no file.
- Re-pointing allocations that PocketBase clears because `assets` is rebuilt
with new ids each seed (operators, purchase lines).
- One QR encoder for screen and PDF, so a printed code cannot drift from the one
on screen. pdf-lib writes real vector PDFs; pdfjs-dist only reads them.
- Every figure is null-safe: unknown is never rendered as zero.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
PHI 180 prints "Westpark" where the register says "West Park", so a
spacing-insensitive fold looks like an obvious typo fix. Tried it, and it is wrong:
the register ALSO carries both "Autumns Gate" and "Autumnsgate", and no rule can
tell a missing space from two genuinely different places — it merged that pair.
Reverted lib/sites.ts to its previous conservative behaviour and pinned the
decision with a test. PHI 180's stored name was corrected to "West Park" by hand
instead. Merging the two Autumn sites is the client's call, not a side effect of a
re-import.
The name on an invoice means two different things. On an internal invoice it is a
SITE, transcribed from the invoice's own description. On an external invoice it is
the SUPPLIER - and the PDF does not print the supplier's company name at all, so
there is nothing to transcribe and a human has to type it.
`invoices.site` stays the single field; the column header follows the page (Site on
Internal, Supplier on External) and only the external one is editable, via
components/SupplierCell.tsx and PATCH /api/invoices/:id/site. It saves on blur or
Enter, never per keystroke, and an empty value clears the name so a stray
description fragment can be removed rather than displayed as a supplier.
Sites stop taking their names from external invoices, in both places:
- syncSitesFromInvoices only creates sites from internal invoices, so a job
description can never be registered as a yard.
- buildSiteSummaries only counts internal invoice lines towards a site, which is
what /sites and the dashboard's per-site chart read.
This is the "Move containers" case. PHI 192's description is "Crane Truck Hire 17
September 2026 Move containers", which had registered a site literally called
"Move containers" - a job, not a yard - on /sites, on the dashboard's per-site
chart and in the plant register's site filter. The record stays in the collection
(sites are never deleted) but is no longer surfaced; the count went 13 -> 12.
External income is not lost by this - it is booked to a machine and still appears on
/income and /charts. It is simply not a site.
The intake route stops resolving an external invoice's text against the site list,
which would have invented a site out of a description, and reports needsSupplier so
the import toast says the name is outstanding.
npm run seed now captures existing invoice names before it wipes the collection and
re-applies them where data/source does not specify one - the same data-loss trap the
uploaded PDFs already had. A JSON name always wins, so internal sites are unchanged.
Verified: typecheck clean, 45 tests pass (4 new, covering the "Move containers" case
directly), production build green, the new PATCH route 401s when anonymous, and
/sites plus both invoice pages pass the mobile checklist at 375x812 and 768x1024. The
supplier edit was exercised end to end and the test value reverted.
Still open: the three external invoices (PHI 178/186/192) have no supplier name yet
and none can be derived from the data. They show "Set supplier" until the client
supplies them.
Note: lib/rows.ts, lib/server-data.ts and the running/insurance feature are
someone else's in-flight work and were deliberately left uncommitted here.
Renames the existing /income/invoices page to "Internal Invoices" and adds a
sibling /income/external-invoices page, splitting ONE `invoices` collection by
the debtor printed on the invoice: a Mega group company is internal, anything
else is external.
Never two collections. An invoice must not be able to exist on neither page, and
the halves must stay reconcilable against /income. Both routes render through the
single components/InvoiceRegisterPage.tsx so they cannot drift apart.
lib/invoice-party-policy.json holds the group entity list and lib/invoice-party.ts
does the matching. Matching is on debtor name OR debtor_no, never name alone:
all three external invoices (PHI 178/186/192) carry an empty debtor name and only
a third-party number, so a name-only match would misfile every one of them. An
invoice naming neither is never internal - it lands on External and is reported
as unclassified rather than silently filed.
The split is 16 internal / 3 external across the 19 invoices in the register.
Also fixes three things the split would otherwise break:
- Booking a line, importing a PDF and retrying an intake can all land on either
side depending on the debtor, so the five write paths only revalidated
/income/invoices and would have left the other page stale. They now call
revalidateInvoicePages() from lib/invoice-revalidate.ts. Route paths live in
lib/invoice-routes.ts, which imports no next/* so a client component may import
it; the revalidate helper imports next/cache and is server-only.
- A site's "Go and assign them" link hard-coded the internal path, so a site whose
outstanding lines sit on external invoices would dead-end. SiteSummary now
carries the outstanding lines split by party.
- verify-auth-routes.mjs now covers the new route.
The two routes are siblings by design: isGroupActive matches a child by path
prefix, so a nested /income/invoices/external would highlight both leaves at once.
Verified: typecheck clean, 41 tests pass (7 new), production build green,
anonymous access to both routes 307s to /login, and the mobile checklist passes at
375x812 and 768x1024 - no horizontal page scroll, no tap target under 44px, no
text under 12px. The nested line-item table still scrolls inside its own container
without stretching the outer table.
Note: lib/rows.ts, lib/server-data.ts and the running/insurance feature are
someone else's in-flight work and were deliberately left uncommitted here.
PHI 179 was refused: "Machine lines total R5265 but the invoice subtotal is
R13730". Three separate faults, each of which only this invoice exposed.
1. The parser read ONE line per machine. A machine hired over more than one
period is printed as one heading followed by a repeating block per charge,
and PHI 179 is a single CT01 crane truck billed on 4, 16 and 18 Sep at
R5 265 + R3 200 + R5 265. The parser only ever looked at the first block,
so two thirds of the invoice went missing and the arithmetic check — which
did its job — rejected it. extractLines() now walks y-banded rows and emits
one line per money row, all carrying the machine's code. A machine billed
once still yields exactly one line, which is what PHI 168/169 do.
The banding matters: pdfjs splits one printed row across two y positions
(the TOTAL sits ~2pt above the rest), so the fixed +-12pt window the old
code used was never a row, it was a coincidence.
2. siteFromDescription required the description to START with "Hire Plant" or
"Plant Hire". PHI 179 reads "Crane Truck Hire Sep 2026 Cosmo" — it leads
with the machine type — so the regex returned "" and the invoice linked to
no site at all. The month/year pair is the part every description shares,
so that is the anchor now.
3. Even read correctly the site is "Cosmo", where every other invoice says
"Cosmo City". Sites are DERIVED from the invoice wording, so saving the
abbreviation would create a second "Cosmo" and split this customer across
two rows on /sites. resolveSiteName() folds a shorter whole-word prefix
onto a site already in the register, one direction only, so a genuinely new
site is still recorded as new.
Also: a problem invoice stored its PDF with no way to open it. The inbox
reported the failure but not the document behind it, and /api/invoices/:id/
document only serves imported invoices — the one case you most want to inspect.
New GET /api/invoices/intake/:id/document, plus a PDF link on each inbox row.
Verified: PHI 179 reconciles in full (R13 730 + R2 059.50 VAT = R15 789.50,
three lines, each balancing). PHI 168 and PHI 169 still reproduce their hand
extraction field for field, including line count. 40 tests, typecheck clean.
Every PDF import failed in production with "Setting up fake worker failed:
Cannot find module '/app/node_modules/pdfjs-dist/legacy/build/pdf.worker.mjs'".
output: "standalone" ships only the files Next's output tracer can see. It
traced pdf.mjs, because lib/invoice-parser.ts imports it by literal path,
but the worker's sole reference is a createRequire(...).resolve() call,
which the tracer does not follow. So the image contained pdf.mjs alone,
pdfjs fell back to its default "./pdf.worker.mjs" relative to pdf.mjs, and
the import hit a file that was never copied.
Copy the whole package in the runner stage: the worker has to sit next to
pdf.mjs, and so do the standard fonts, which the parser needs because it
passes useSystemFonts. Verified against the reconstructed runner layout —
the old layout reproduces the error verbatim, the new one parses and
extracts text.
Also in lib/invoice-parser.ts: workerPinned was set before the resolve, so
a failed resolve was never retried; and the empty catch swallowed the
MODULE_NOT_FOUND that named the real cause. Both fixed.
Add PocketBase login, first-sign-in password changes, account settings,
and user activation, reactivation and deletion with self-removal guards.
Protect application pages and APIs and keep private pages out of PWA
caches.
Resolve plant locations from site assignments and improve map controls,
profit chart views, navigation and mobile table layouts.
Validation: production build and TypeScript passed; 28 unit tests passed.
Backend access integration tests and mobile verification are documented.
The field is `assets.is_active`. All 7 inactive machines have no income at all
— the three generators, two porta camps, AEB Plant Versekering and the Diesel
Truck — so on the income list they were a flat row of zeros and nothing else,
reading as "idle" when they are actually out of the fleet.
They are now hidden by default. The rows are not dropped from the data: the
filter lives in the view, so Active / All / Inactive is a client-side toggle
with no refetch, and each shows its count so a filter that silently hides rows
is obvious. A machine hidden by the filter also collapses if it was expanded.
The YTD income and profit tiles moved into the view so they sum only what is
visible — otherwise the headline would report the whole fleet while the list
below it showed a subset.
/charts is unchanged: it passes no filter and still sees everything.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two things this question turned up.
The upload DID store the PDF, but on the intake record, never on the invoice
— so "Open invoice PDF" 404'd for every invoice imported through the app
while working for the older ones. The file now lives on invoices.source_pdf
and the intake record keeps only the provenance (who sent it, what was
parsed), rather than a second copy of the file. The document endpoint also
falls back to the intake record, which makes the seven already-stored
documents reachable again without a migration. All 10 now open.
The machine combobox searched only the register's own words, so an invoice
line reading "CB22 2.2 TON Roller Vibration" could never be matched to the
asset filed as "CAT 2,4TON RV" — the words simply were not in the list. The
line's own invoice code and description are now searchable too, so the two
sides of the same machine can actually be found from either direction.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A container line prints a generic code ("MPLANT05") that the plant register
does not carry, so it had no asset to book to and sat unbooked forever. Each
site now records the container it hires — the code the invoice uses and the
plant item it books to — and a line arriving on an invoice for that site is
allocated to it automatically on import.
The lookup is scoped to the invoice's OWN site, not globally: two sites can
each hire an "MPLANT05" unit, and each line must land on the unit actually at
its own site. Covered by unit tests rather than by deleting a live invoice
and re-importing it.
A code with no asset is refused on save — it would auto-allocate to nothing —
and both or neither is required.
Assigned and booked: Autumns Gate "MPLANT05" -> SC02, The Hills "MPLANT05" ->
SC03, and The Hills' stuck line is now booked and earning. Container lines on
future invoices for those two sites will be booked without anyone touching them.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`assets` already carried latitude/longitude, but `sites` had nowhere to put a
pin — so there was no way to locate a site. Both fields added, matching the
plant collection's shape so the same map component can plot either.
Coordinates are entered as two plain number fields with an "open in maps" link
to verify the point, rather than a drag-to-pin map: the in-app Leaflet map is
still being worked on, and a coordinate is usually copied off some other map
anyway. Clearing removes the pin rather than leaving half a coordinate, which
would plot in the Gulf of Guinea and read as "located".
Bounds are checked server-side, not just in the form: a point outside South Africa
is refused with the numbers echoed back, because a swapped pair or a dropped
digit is far likelier than a machine abroad. 0,0 is rejected by the same rule.
The sites list marks each row as pinned or "no pin", with a banner counting the
gaps, so an unlocated site is visible without opening it.
While checking this, found that all 44 assets carry the SAME coordinate
(-26.1016, 28.3487) — the Plant Map currently stacks every marker on one pin
while reporting "44 located on the map". Left alone, but worth knowing.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The container lines (MPLANT04/MPLANT05) have no matching plant item, so they
sat unbooked forever with no way to account for them. They can now be booked
to a SITE instead.
`sites` is a new PocketBase collection derived from the invoices — each
distinct invoice site becomes a site, created as invoices are imported. They
are never hand-typed, and never deleted: a site can carry notes and hold line
bookings, so removing one would orphan that history.
/sites lists every site with its revenue ex VAT, its VAT, the total billed,
how many invoices and machines it carries, and how many lines are still
outstanding. Each row links to a detail page listing the site's invoices and
every line item with its ex-VAT/VAT/total split. Nav: Dashboard is now a
group with Overview and Sites.
Booking a line to a site posts NO income — there is no machine to carry it —
it only marks the line accounted for, so it stops showing as unbooked. Exactly
one of booked_asset / booked_site is ever set, and a line with neither is what
surfaces as unbooked everywhere.
One container per site, as specified: once a machine-less line has taken a
site, that site is withheld from the next one's picker and shown disabled
("already has one") rather than hidden. Free sites sort to the top. The rule is
enforced server-side too, so it does not depend on the UI being the only way in —
re-posting a taken site is refused with 409. Verified: booking The Hills, then
trying again, then taking West Park, and the remaining line sees 8 free and 2
taken. Clearing a booking frees its site.
The site picker only appears on lines that need it — no machine, or one already
booked to a site — so fully-booked rows keep a single control.
Also fixed the Sidebar's group-active check, which derived its prefix from the
first child. For a group whose first child is "/" that yields "/" and matched
every route, so Dashboard would have been highlighted on every page.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Extraction was previously manual: an agent read each PDF, mapped the columns
by hand and wrote data/source/invoice-*.json. That was the only way anything
got in, and the upload button just filed the document without reading it.
That supplier's report is one fixed template — the columns sit at identical
x-positions on every invoice, and only the line count and page count vary —
so the figures are now read by coordinate instead. Deliberately not an AI
extractor: this input does not need one, and a deterministic parse that fails
loudly is worth more here than a flexible one that can hallucinate a total.
lib/invoice-parser.ts reads the header, the machine lines across all pages,
the "Plant Hire Total" row and the SUB TOTAL / Escalation / PLUS VAT /
INVOICE TOTAL block, then applies the same arithmetic gates the seed does:
lines must sum to the subtotal, each line must satisfy qty x rate = amount
and amount + VAT = total, and VAT must match the stated rate. Anything that
does not reconcile is refused with the reason — never partially imported.
Validated by parsing all five existing invoices and comparing every field
against the hand-extracted JSON: identical, including the R24,205.13-VAT
column that a plain text read gets wrong. PHI 169 was then deleted and
re-ingested through the HTTP endpoint alone and came back field-for-field
identical, with no agent involved.
- "Add Invoice" drops a PDF in and imports it; lines are matched to plant
items by the code the invoice prints, and an unmatched line (the
container codes MPLANT04/MPLANT05) is left unassigned rather than guessed.
- A "Problem invoices" inbox lists every PDF that failed, with the reason,
and Retry re-reads the stored document and re-runs the parse. Retry
re-reports rather than claiming success, and only files imported data.
- invoice_intake collection records each attempt.
pdfjs-dist is in serverExternalPackages: bundled, it rewrites its own lazy
worker import to a .next path absent from the standalone image and every
parse dies with "Setting up fake worker failed". The parser also copies the
buffer before handing it over, since pdfjs transfers and detaches it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds an Invoices sub-menu under /income with a summary table (one row per
invoice, click to expand the full detail) and the data model behind it.
Data:
- invoices + invoice_lines PocketBase collections, created idempotently by
scripts/setup-invoice-collections.mjs
- line items transcribed from PHI 166/167/171 with per-invoice arithmetic
validation in the seed; a bad invoice is refused without blocking the rest
- invoice-*.json in data/source are auto-imported, so adding an invoice is
one file
Booking:
- manual book-in per line (Booked to), grouped by category
- POST /api/invoice-lines/:id/book moves the income row rather than adding a
second one, so a booking can be changed freely
- scripts/book-invoice.mjs is idempotent: rows are stamped with
monthly_income.invoice_line and replaced on re-run
- booked amount follows lib/invoice-booking-policy.json (bookInclusiveVat),
read by both the app and the CLI so they cannot disagree
Money:
- the R24,205.13 column on these invoices is PLUS VAT, not escalation. The
seed now rejects VAT that disagrees with the stated rate.
- booked amounts are VAT-inclusive per the client ruling of 2026-10-01; the
VAT stays visible rather than hidden.
Uploads:
- drag-and-drop PDF attached to invoices.source_pdf
- GET /api/invoices/:id/document proxies it — the collection is rule-locked,
so a direct PocketBase /api/files link 404s in a browser
Fixes a month-aggregation bug this introduced: buildIncomeRows assigned into
months[i], so a machine with two income rows in one month (one per invoice,
which is normal multi-site use) showed only the last. SS01 September read
R20,700 instead of R35,305 while its own YTD included both. Months now
accumulate, per-month profit is computed once after accumulation, and
lib/rows.test.ts pins it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Part A — Round 3 regressions:
- A.1: verify-cost-reconciliation.mjs now loads .env.local, wraps in try/catch, exits 1 on any failure
- A.2: Vehicle Costs restored Santam — back to R 14,996.31 (matches row-by-row sum)
- A.3: incl<excl / VAT math / VAT>20% now FATAL — seed exits 2 with full report (4 anomalies on Charl-CCS + Buildsmart)
- A.4: Reconciliation target R 694,962.93 with both deltas itemised (Personnel +R19,800, Santam -R5,322.44, unexplained R 0.00)
- A.5: 'Lines' view uses actual lines (recharts LineChart), no fills; fills only in 'Cost stack'
Part B — Mobile standard:
- B.1: header wraps to 2 rows on mobile; YTD badge cards stack; page-wide overflow eliminated on /income, /charts, /overheads, /running, /expenses
- B.2: IncomeView card row layout stacked — name gets its own line on mobile, never truncated to single char
- B.3: Plant type filter is a <select> dropdown below lg (was 18 pills wrapping to 13 rows); same for sort on /income and /running
- B.4: Plant table first column sticky; -webkit-overflow-scrolling: touch; tables scroll inside their own container
- B.5: All buttons/links use min-h-[44px] tap targets; text below 12px is bumped where it matters
- B.6: Charts legend wraps below title; chart min-height h-44 → h-52 on mobile
- B.7: paddingTop env(safe-area-inset-top) on sticky header for notch/home indicator clearance
AGENTS.md created with the standing mobile checklist rule.
- A.1: fixed_expenses per month now threaded through to chart bucket
- A.2: null = no data (forecast), 0 = real plotted zero — distinguishable
- A.3: x-axis clipped to last actual month (IncomeAreaChart + IncomeBarChart + MachineLineChart)
- A.4: chart hues as CSS vars (--color-chart-income/fixed/running) — deeper steps of same hues, validated for CVD
- A.5: chart-type toggle (Lines / Cost stack / Profit) + localStorage persistence + dynamic legend
- A.6: profit on charts page comes from computeProfit()
- B.1: deleted /expenses/plant-overheads, /expenses/insurance, /expenses/tracking (all empty); added /expenses/vehicles; ExpenseSectionPage now has an empty state
- B.2: captured R 157,200 Personnel block, R 100,000 Maintenance, R 10,000 Petty Cash; roll-up reconciles to R 675,162.93 (= sum of non-Plant non-Santam rows; workbook grand total R 1,110,486.87 is internally off by R 14,477.56 vs its own rows)
- B.3: seed flags incl<excl, VAT>20%, broken VAT math — does NOT silently correct; 4 anomalies reported on Charl-CCS + Buildsmart
- B.4: noted that workbook Vehicle Costs subtotal skips Santam (app R 9,673.87 is correct; workbook is wrong)
- B.2 reconciliation assertion added to verify-cost-reconciliation.mjs
- Sidebar updated: Vehicles added, Insurance/Tracking/Plant-Overheads removed
