Documentation
Biloh documentation
The operating system for field-service businesses, run by talking to your AI assistant.
How Biloh works, how to do things in it, and how it is built. Each page opens with a plain-language summary, the detail follows, and the tools and source files it relies on are listed at the foot. The full corpus for AI agents is at /llms-full.txt.
Tutorials
- Close your first month
A first run through Biloh's books: register three accounts, import a statement, reconcile in and out, check the envelopes, close the month and read the BAS.
How-to guides
- Amending a proposal after you have sent it
A sent proposal is immutable. Supersede it with an amended copy that keeps the audit trail and redirects the client's original signing link to the new one.
- Bill an extra service you did on the day
Add an extra service you performed on the day with add_adhoc_service — it routes into the client's existing invoicing cadence automatically.
- Change a recurring series without double-booking anyone
What happens to booked visits when you change a series' day or cadence: pending contractor confirmation, the hold badge, and the period guard.
- Chase overdue invoices with one reminder per client
See who owes you, prepare one reminder per overdue client with a link to pay, check each one, and send only the ones you tick.
- Close a month and a quarter
Prove the bank feed is complete, lock the month's cash figures, roll the quarter up, and reopen with a reason when a late payment arrives.
- Dispatch a job to a subcontractor, from assignment to their bill
Assign a job, clear the agreement check, send the work order, let the subcontractor accept and complete it, and see their bill appear.
- Dispatching and triaging jobs
Dispatch a job to a contractor, act on it from the Job Command Sheet, and clear what needs attention — overdue, missed, and unassigned work.
- Find out who changed what, and how
Ask your assistant, or open the Activity page, to see who changed a record, whether it was a person or an assistant, and the old and new values.
- Migrating a client book from another system
Move live clients off an old CRM client by client — verify the entity, stand up the service, backfill completed work, and bill it without losing history.
- How to offer options on a proposal
Let the client choose one option on a proposal — monthly, quarterly or six-monthly — and book only the option they pick when they sign online.
- Onboard a client in one sentence
Describe a client in plain words on the onboarding page and review a complete draft — nothing is created until you confirm.
- Personalise a staged send
Write a one-off note into an invoice, proposal or statement email, and read the byte-for-byte preview before the send is approved.
- Prepare the BAS and the accountant pack
Read the quarter's BAS figures on the ATO labels, generate the one-ZIP pack for your accountant, and keep the compliance calendar lodged.
- Read your money brief: what you can pay yourself this week
Open Pay day or ask your assistant how the business is going: this pay day's three transfers, what needs you, your accounts and the bills due.
- Reconcile money in
Match each deposit in the bank feed to the invoice it pays, handle the ones that are not invoice income, and teach Biloh the payer for next time.
- Reconcile money out
Settle contractor bills against bank debits, code supplier spend with its GST evidence, pair receipts from the shoebox, and split mixed lines.
- Record a cash payment taken on site
You printed the invoice, handed it over and were paid in cash. How to get that into the books correctly, dated when the money actually moved.
- Register your bank accounts and import a statement
Set up the everyday, tax set-aside and contractor buffer accounts once, then bring each week's bank export into Biloh so nothing is missed.
- Review Biloh on the demo business: a reviewer runbook
Connect an assistant to Biloh's public demo, sign in, then run five prompts that should work, two that should be refused and one that is contained.
- Schedule a monthly visit on a weekday, not a date
Set day_of_week, week_of_month and an anchor date so a recurring visit lands on the second Tuesday, the last Friday, or any nth weekday.
- Schedule recurring work before a proposal is signed
Turn off the activation gate to schedule and dispatch recurring work on a verbal agreement, keeping the proposal ready but unsent.
- How to send a proposal
Build a proposal in biloh, preview the investment summary, and send it to your client for a legally-binding portal acceptance — by chat or in the app.
- Track assets and depreciation
Put a laptop, a mower or a trailer on the asset register from the bank debit that bought it, choose the method, and read the year's schedule.
- Triage an inbound client request
Pick up a request a client sent from their portal, decide whether to quote or decline it, and turn it into a priced proposal.
- Triage a draft invoice queue after a billing cutover
Stop a migration from looking like double-billing: sort the draft queue by evidence, then send each invoice with the note it actually needs.
- Verify an email actually reached your client
Check per-recipient delivery evidence for any send — and tell a mail-app display problem from a genuinely empty or missing email.
- Work your invoice list without opening a single invoice
Read the whole receivables position from one feed — who owes, how late, which drafts are stuck — then record a payment in place.
Reference
- The attention digest: a dashboard your agent actually reads
Reference for get_attention_digest — the MCP tool that carries the operator's outstanding-attention queue into every agent conversation.
- Bank import and close refusal codes
Every code the finance engine refuses with, what it means, what figures come with it, and what to do next. A refusal is the product working.
- Chasing overdue invoices: the tool sequence for AI assistants
How an assistant finds overdue clients, stages one reminder each, sends the approved ones, and reads nothing_staged — with inputs, fields and refusals.
- Dispatching a job: the tool sequence for AI assistants
The exact tools an assistant calls to assign, gate, send, accept and complete a subcontracted job — inputs, returned fields and every refusal.
- Finance MCP tools
The finance engine's tool surface by stage: bank feed, money in, money out, transfers and envelopes, close ladder, BAS, reports, assets, calendar and pack.
- Finance settings
Every tunable that shapes the finance engine per business: bank feed guards, GST evidence thresholds, envelopes, obligations, assets and the pack.
- Invoice list fields: what an agent gets per row
Reference for the fields list_invoices returns — client identity, live overdue position and pre-computed ageing — and which one to read for which question.
- Invoice send: gates and guards
The three-leg send chain, the approval-free second caller, the tax validator that runs at approval, and the duplicate guard — what each blocks and why.
- Matching bank deposits: the four shapes and the tool for each
For AI assistants: read each incoming deposit's shape first, then match it with the one tool that records it correctly and can't pay twice.
- Connecting Biloh over MCP
How to connect a Biloh tenant to an AI assistant over the Model Context Protocol — the endpoint, authentication, personas, and the operator toolset.
- The money brief: the tool sequence for AI assistants
get_money_brief, get_owner_pay_plan and get_envelope_targets — inputs, every field an assistant relays, the compact default, and what to say about money.
- Route optimization: the runs bolt-on
Runs group a day's stops in Biloh. Ordering them by hand is free; an optional paid solver sequences them and hands the route to your maps app.
- Service request MCP tools
The five MCP tools that let an assistant work a client's inbound request queue: list, read, review, decline and quote.
- Write safety: expected_tenant and target_tenant_id
Two guard rails that make a misrouted write fail loudly instead of landing in the wrong tenant, and the exact errors they raise.
Explanation
- Backfilling work you already did
Record completed visits from before a migration at their original price, decide whether a contractor gets paid, and let the billing cadence bill them.
- Cash-basis BAS from the bank feed
How Biloh turns matched deposits and coded debits into G1, 1A, 1B and the net GST position, and why 1B is the claimable figure.
- How client requests close the loop
Once a client is onboarded their portal becomes the channel they send new work through, and every request lands in your queue as actionable work.
- Who decides whether a job needs photos?
Photo and note requirements on completion resolve through four levels — job, series, client and contractor, then your default — with the strictest rule winning.
- Delivery models: dispatch, self-perform, or both
One delivery-model setting adapts Biloh to operators who subcontract every job and to owner-operators who do the work, without splitting into two products.
- Envelopes: the tax set-aside and the contractor buffer
How Biloh tells you what should be sitting in your tax and contractor accounts right now, measures what is, and pairs the sweeps between them.
- One proposal, many sites
A multi-site proposal prices each premises on its own line, subtotals per site, and stands up a separate service line at every site when the client accepts.
- Scheduling jobs by the day, not the minute
Why a field-service schedule models jobs at day granularity, and how editing a recurring series splits into this-occurrence and all-future changes.
- Signed work never disappears: sold-visit decision cards
When an accepted proposal contains a visit dated in the past, biloh raises a decision card instead of silently never scheduling it.
- The balance chain: how Biloh knows a month is complete
Why every imported bank line is tied by the bank's own running balance, and what the chain guard refuses on import and at close.
- The three voices of a service
One service speaks three ways: a sales pitch for customers, a legal scope for contracts, and an operational scope for the crew doing the work.
- How Biloh handles money: the two Stripe tills
How Biloh separates platform subscription billing from each business charging its own customers — two independent Stripe tills.
- When completing a job bills the client
Field-service billing cadence is per-client: invoice each job on completion, consolidate a period, bill on the period's last job, or invoice by hand.
- Why a contractor can't be assigned to a job
The compliance gate checks capability, agreement, insurance and availability before any assignment — and names the exact reason each contractor failed.
- A payment link you can store
A Stripe checkout session expires by design. Any payment link you store on a record, print, or hand over has to be the portal link instead.
- How outbound email is addressed and signed
Why a company name is never used as a greeting, how the fallback ladder works, and how your own note suppresses a duplicate greeting or sign-off.
- Why your brand assets should outlive your designer
How Biloh's Brand Pack keeps finished files AND editable source masters with your business, so any designer can continue the work.
- Closing the books by chat
What actually happens when an operator tells an AI assistant to reconcile the bank, close the month and produce the BAS in Biloh.
- The Biloh finance engine: accounting you can run by chat
Bank feed, reconciliation, month and quarter close, BAS, P&L, balance sheet and the accountant pack, all driveable by natural language.
- How payment terms are decided on an invoice
The cascade from client to business default, why a due date is not a payment term, and the rule that an invoice never overstates the credit given.
- Is my business data kept in Australia?
Yes. Biloh stores every business's data in Sydney, Australia, tied to that business on every request, with export and deletion from Settings.
- One schedule, one truth: how biloh keeps the calendar honest
The integrity invariant behind biloh scheduling: the calendar equals the contract, and when it can't, a human is told — never silently.
- Can it handle residential and commercial clients?
Residential and commercial clients run on one engine. What changes is client type, service audience, payment defaults and price presentation.
- Trading name versus legal entity: which name shows where
Operator screens name a business the way you know it. Tax invoices, statements and the accounting mirror carry the registered entity — and a test enforces both.
- What a field-service scheduling engine should be able to express
The recurring-work patterns real service contracts contain, and how biloh represents each one — including the ones most tools can't.
- Which AI assistants work with Biloh?
Claude and Grok; ChatGPT with the core tool list — and any assistant that speaks MCP — with permissions you choose, at no extra cost on any plan.
- What is Biloh?
Biloh is the operating system for field-service businesses, run by talking to your AI assistant: quotes, visits, invoices and the books.
Engineering notes
- A failure ceiling that only goes down
A committed failure ceiling, calibrated only from CI, that refuses stale or partial evidence — and becomes the zero-failure gate when it reaches zero.
- A record from another business answers "not found"
How Biloh binds every request to one business before it reads or writes, so an id from another business answers 404 and changes nothing.
- A public promise is a test, not a sentence
How each thing Biloh says it will not do is backed by a test that fails the build the moment a new feature would make it untrue.
- An orientation payload an agent can actually read
A read-me-first tool that returns 100KB is unreadable inside an agent's context budget. Make the default lean, put the full detail behind an explicit flag.
- Show the price you'll charge: one source of truth
Show prices from the same source that charges the customer. Copying a price into a second surface invites silent displayed-versus-charged drift.
- Drag is a desktop idiom; the phone wants a tap
Drag-and-drop dispatch boards are desktop tools. On touch a press-and-move is a scroll, so the field surface has to be tap-first, not drag-first.
- Every outbound URL is checked before the server fetches it
Biloh's server only fetches a URL a business gave it after checking every resolved address is public, and it re-checks each redirect hop.
- Every record needs a visible bucket
Grouping a list into filters can leave records in no group at all — present in the data, invisible on screen. Make the buckets a partition and assert the union.
- Five ways a test suite lies to you
Silent-pass patterns found on the road to zero failing tests: vacuous scanners, swallowed errors, invisible todos, and a reporter that never ran.
- Freeze the baseline, then burn it down
Convert a never-green check into a frozen offender list that blocks new debt today and only shrinks, with invariants that keep the list honest.
- The gap between a green build and a live deploy
Lessons from building a docs system into a deploy-on-every-push platform: a green local build and a working deployment are different claims.
- Lessons from shipping agent-facing MCP tools
Lessons from shipping a batch of MCP tools: test the consumer not just the logic, surface what agents need, and watch the build and version traps.
- When the money arrives but can't be recorded
When a provider confirms a payment your system can't record, alert a human and still acknowledge the provider — never fail silently.
- Making a multi-connector MCP setup safe to act on
How Biloh stops an agent holding several tenant connectors from acting on the wrong one: identity, a per-response stamp, a mismatch guard, confirm-gates.
- OAuth codes are single-use and a replayed refresh token ends the grant
How Biloh's token endpoint makes each sign-in code redeemable once, binds refresh tokens to their app, and revokes a grant whose old token is replayed.
- One home, locked in both directions
A display rule and its compliance counterpart point opposite ways. Give each one home, then write the structural test that guards both boundaries.
- One question, one home: why parity beats correctness
A case where the UI and the agent tool answered the same question differently, and the correct half was not enough to prevent a false bug report.
- One write path, many callers
Why every mutation should funnel through one core that the UI and the agent both call — and the billing bug that appears when a caller skips it.
- Put the yes where the thumb is
A field app's primary action belongs in the thumb zone, pinned and dominant — and the destructive options belong below the content, not above it.
- Quarantine as ratified contract, not hidden debt
When a failing test asserts ratified-but-unbuilt behaviour, preserve it verbatim in an integrity-locked quarantine its work package must turn green.
- Shipping a feature beside an agent that also ships
When an autonomous worker merges to the same branch you are building on, version numbers collide and edits overlap. Merge, never overwrite.
- The MCP endpoint checks the browser's Origin and never leaks internals
Biloh's MCP endpoint refuses browser calls from unlisted sites and turns every tool error into a plain message with a reference.
- Tool discoverability for agents
How an agent finds the right tool among hundreds — a categorised map, intent search, and the zero-result rate as the signal the catalogue works.
- Trust the signed account, not the webhook's metadata
A payment webhook must bind each charge to the provider's signed account, not to client-supplied metadata — the pattern that blocks cross-tenant spoofing.
- Two places, one fact
A permission was stored in two places. The form wrote one, the gate read the other — so a user's saved choice was invisible to the system enforcing it.
- Reading a tenant setting: unwrap the envelope
Governed settings writes wrap the value as {v:...}, so a raw read silently returns the default. The one unwrapper to use, and the lint that enforces it.
- Verifying the tenant that isn't your default
A test harness that injects tenant context can't catch a tenant-resolution bug. Only live use on a non-default tenant exposed a 401 the suite couldn't see.
- When an agent files a bug against working code
An agent reported a broken send. The send was fine — its own reporting tool was lying to it. How to triage a report written by a confident reader.
- Whose "today" is it? Timezones in a scheduling engine
A scheduling product that computes today in UTC shows the wrong day to most of the world. Resolve the day in the tenant's timezone and lock it with a test.
- A handler nothing subscribes to does nothing
An event handler can be unit-tested yet never run in production if nothing subscribes it to its event. Verify the wiring, not just the handler.
Field notes
- One field day run by voice: what an agent closed for the owner
A real day, anonymised: the owner worked on the tools while an agent quoted, reported, invoiced and reconciled inside the live business system.
- A branded job report that goes out with the invoice
Site photos become a branded report in the business's own colours, attached to the invoice or quote email in one step. Used with real clients from day one.
- A finished job that bills itself, and gets paid
The contractor marks the job done on their phone; seconds later the client has the invoice and a card link. Four homeowners billed this way, four paid.
- Each repair's photos printed right under the repair
Job reports now print every repair with its own before, during and after photos underneath, the way the owner lays out reports by hand.
- Proving a repair report and a client's own PDF ride with the invoice
Before using it with clients, the owner had an assistant prove both paths end to end. Both worked first time, and real clients got it the same day.