Read Me First

Welcome. This is the front door to AI-Native Accounting Software — a program that keeps a business's financial records ("the books") accurately and permanently, brings in your bank activity, and uses artificial intelligence (AI) to suggest how each item should be recorded while a person always makes the final decision. This document is written for someone who has never seen the project before and doesn't need any accounting or technical background. Read it top to bottom in about twenty-five minutes, or jump straight to the question you have:

1. Who this is for
2. What it does
3. The world it lives in
4. What surrounds it
5. The first thing to do
6. Setting up your complete environment
7. Day-to-day use
8. Weekly, monthly, and long-term duties
9. The demo data, and starting fresh
10. Common questions and gotchas
11. Glossary — plain words for every term
12. The other documents, and where to get help

---

1. Who this is for

Four kinds of people get value from this software. You'll probably recognise yourself in one of them:

• Founders and business operators without accounting training. You run a startup or small business. You need books you can trust, a clear picture of money coming in and going out, and as little manual data entry as possible — without hiring a finance team just to stay organised.
• Accountants and bookkeepers, whether in-house or at a firm looking after many clients. You live in the books every day: coding transactions, reviewing what the AI suggests, approving entries, closing each month, and producing financial statements. This software is built to make that work faster without ever taking the decision out of your hands.
• Finance leaders at organisations that must run their own systems. Some organisations — for legal, regulatory, or policy reasons — cannot put their financial records in someone else's cloud service. This software is self-hostable: you can run the entire thing on computers you control, with real access control and a complete, tamper-evident history of every change.
• Developers and integrators. The software is open source (its full program code is public and free to use and modify) and everything the screens can do is also available to other programs through its API — a documented way for software to talk to software — so it can be wired into other systems.

2. What it does

In one sentence: it keeps a permanent, always-balanced set of books, pulls in your bank activity, lets AI do the tedious suggesting, and leaves every decision with a human.

Breaking that down:

• It keeps the books using double-entry accounting — the centuries-old method every accountant trusts, where each event is recorded in two places (what you got, and where it came from) so the records always balance and nothing can quietly go missing.
• It will not let the books go out of balance. This is not a nightly check that warns you afterwards; it is a rule enforced deep in the storage layer, so an unbalanced entry cannot be recorded in the first place.
• Nothing posted can ever be altered. Once an entry is part of the permanent record it cannot be edited or deleted by anyone. A mistake is corrected by posting a reversal — a mirror-image entry that cancels it, with both left visible.
• It brings in your bank activity and proposes how each transaction should be recorded, with a plain-language reason and a stated confidence.
• It drafts entries from documents. Give it an invoice, a receipt or a statement and it proposes a complete double-entry, showing the source text it worked from.
• A person always decides. Nothing the AI produces reaches the books on its own. Accepting a suggestion is what creates the entry, and an AI-drafted entry must be approved by someone other than whoever accepted it.
• It handles the everyday trading cycle — customer invoices, supplier bills, and the payments that settle them — writing the correct accounting entries for you.
• It produces the reports the business actually needs: trial balance, income statement, balance sheet, cash flow, and an aged view of who owes you and whom you owe.

It also carries a set of capabilities you would not normally expect to find outside expensive commercial packages:

• Revenue recognition. Contracts split into performance obligations, each satisfied at a point in time or across a period, with the price allocated between them and a schedule showing what has been recognised and what is still deferred.
• Group consolidation. Combine several companies you belong to into one set of figures, with intercompany amounts eliminated — and a warning when two entities' records of the same dealing disagree.
• Financial intelligence. Runway, burn rate, recurring revenue, gross margin, people cost and revenue per customer, each able to show the formula and the accounts it was computed from. Where a figure cannot honestly be produced, it says so instead of showing one.
• Variance analysis. A period-on-period comparison that flags only the movements large enough to matter, by both amount and percentage.
• Plain-language questions. Ask about your books in ordinary English. The figures are read from your records rather than written by the model, and the underlying rows are shown so you can check the answer. This one feature needs a language-model provider to be configured for your installation (see section 10).
• Open exports. A plain-text ledger you can keep in version control, a regulator-ready tagged statement, and electronic invoices in the European standard format.
• Tax and currency support. Your own tax rates, alerts when a rate you are still using has expired, and dated exchange rates for trading in more than one currency.

3. The world it lives in

This software serves the occupation of bookkeeping and accounting — the practice of recording every financial event of a business (sales, purchases, payments, salaries) so that the business always knows its true position and can prove it. The books of a business are not just notes; in most countries they are legal records used for tax filings, audits, raising investment, and settling disputes. That is why this software is so strict about balance, permanence, and traceability.

The business contexts it is built for:

• Startups and small-to-medium businesses that want modern, AI-assisted bookkeeping without the cost or lock-in of the big commercial packages.
• Accounting and bookkeeping firms managing the books of many client companies.
• Groups of companies — a parent and its subsidiaries — that need each entity's own books kept properly and a combined view across them.
• Regulated or privacy-sensitive organisations — those that must keep financial data on their own infrastructure and prove exactly who changed what and when.

It supports the two major rulebooks of accounting — GAAP (used mainly in the United States) and IFRS (used across most of the rest of the world). Each organisation chooses one when it is set up. Amounts can be recorded in multiple currencies, with everything also carried in your organisation's home ("base") currency.

4. What surrounds it

No accounting system lives alone. Here is the traffic in and out, and the people involved:

People who sign in. Every user belongs to an organisation with one of five roles, from most to least powerful:

Role	In plain words
Owner	The person ultimately responsible — full control, including membership
Admin	Runs the system day to day — settings, members, periods
Accountant	Approves and posts entries, closes periods, produces statements
Bookkeeper	Records day-to-day activity and reviews bank transactions
Viewer	Can look, cannot change anything

Give people the least power their job needs; you can always promote later. One person can belong to several organisations with a different role in each, and switches between them using the selector at the top of the screen.

Signing in happens through a shared login service (single sign-on): you use one identity across the platform's applications rather than a separate password for each. Your account in the books is tied to that login identity.

What flows in. Bank transactions — either through a connected bank feed that syncs automatically where available, or through statement files (the common CSV and OFX formats every bank can export) that you upload. Also invoices you raise, bills you receive, documents you hand to the AI drafting screen, exchange rates, and the contact details of the customers and suppliers you trade with.

What flows out. Sales invoices to your customers, including electronic invoices in the European standard format; financial statements and reports for owners, accountants, lenders and auditors; a plain-text ledger export; a regulator-ready tagged statement; and, for integrators, everything is reachable by other software through the API. An AI assistant can also be connected to the books directly — see the document map in section 12.

Who consumes the results. Your own team, your external accountant at year end, auditors who need to trace numbers to their source, and tax authorities via the filings your accountant prepares from these reports.

5. The first thing to do

What "first" means depends on how you arrived. There are three doors in:

a) You're trying the preview or a demo

Both open straight onto the dashboard of a fictional sample company with realistic books already in place. There is nothing to set up. The best first move is simply to explore in this order: Dashboard → Chart of accounts → Journals → Banking → Invoices → Statements — the same tour as Day-to-day use below. Then try the less usual screens: Revenue recognition, Consolidation, Intelligence and Variance analysis.

Section 9 describes exactly what sample data you get and how to clear it.

Demo data is disposable. A hosted demo exists for a short, fixed time and is then removed, along with everything in it. The downloadable preview keeps nothing between runs unless you deliberately ask it to. Don't record anything you want to keep in either.

b) You're starting a fresh, real installation

For a real installation, your organisation is created before anyone signs in, by whoever operates your installation, using the guarded initialization procedure described in production-initialization.md. That procedure creates the essentials: your organisation (name, country, home currency, choice of GAAP or IFRS, financial year), the first owner account, a standard chart of accounts, the first financial year split into monthly periods, and two neutral tax codes.

So the first thing you do in the app is:

1. Sign in with the owner identity that was set up for you.
2. Look around before touching anything: open Chart of accounts and confirm the account list suits your business (you can add or rename — though a few system accounts the software depends on are protected), and check the organisation basics you were set up with.
3. Then work through Setting up your complete environment.

Initialization wipes data. The initialization procedure is deliberately destructive: run against a system that already has data, it deletes that data (it has multiple safeguards and confirmations, but the end result is permanent). It is a first-use tool, not a reset button — and on any real system, a database backup comes first.

c) You're joining an existing installation

If your organisation already uses the software, you'll be invited by an owner or admin and assigned a role. Sign in, find your organisation (if you belong to more than one, there's a switcher at the top of the screen), and start at Day-to-day use. An installation can host more than one organisation; creating an additional one is an administrator action — ask whoever operates your installation.

6. Setting up your complete environment

Do these once, in this order, and the system is fully ready for daily work. The names in bold are the entries in the app's left-hand navigation.

1. Review the chart of accounts (Chart of accounts). This is the list of labelled "buckets" every transaction is filed into — things you own (assets), things you owe (liabilities), what the business is worth (equity), money earned (revenue), and money spent (expenses). A standard set is created for you; add or adjust accounts to fit your business. A few system accounts (like Accounts Receivable and Retained Earnings) are protected from deletion because the software relies on them.
2. Invite your team (Members). Add each person and give them one of the five roles from section 4.
3. Add your real tax rates (Tax rates). After initialization only two neutral codes exist (Exempt and Zero-rated) — placeholders that make invoicing work, not your country's actual rates. Add your jurisdiction's real rates (VAT, GST, sales tax) before you start invoicing. Each rate carries the window of dates it applies to, which is what lets the system warn you later when one has lapsed.
4. Record your contacts (Contacts). The customers you invoice and the suppliers who bill you.
5. Connect your bank (Banking). Add each real bank account, then get transactions flowing: upload a statement file (CSV or OFX — every bank's online portal can export one) or, where available, connect a live bank feed that syncs on demand. Uploading a file is the path that always works, so start there.
6. Confirm your periods (Periods). Check the financial year and its monthly periods match how your business reports.
7. If you trade in more than one currency, enter your rates (Exchange rates). Rates are held per date, and the screen spells out in words which way each pair runs so nobody has to guess.
8. Optional, but worth it early: set up coding rules (Coding rules). A rule says "when a bank line looks like this, always use that account". Rules are checked before the AI, and the first match wins — so anything you are certain about never has to be reviewed again. You can also let the system learn rules from the corrections you make.

That's the whole setup. From here on, the software's job is to keep the daily work small.

7. Day-to-day use

A working session usually looks like this:

Start at the Dashboard. It opens by telling you whether the books tie for the current period, then shows what needs you — entries awaiting review, one ready to post, drafts, overdue customers — followed by what you're owed, what you owe, and a feed of recent activity.

Review incoming bank transactions (Banking). New transactions line up with the AI's proposed account for each, a plain-language reason, and a confidence level shown as a percentage and a high/medium/low band — never colour alone, so the screen reads correctly for everyone. For each one you either Accept (this is the moment a balanced entry is written to the books and the transaction is marked reconciled — matched to the bank's record), Correct (choose the right account — the system records your correction and uses it to make better suggestions next time), or Reject. Re-imported or duplicate transactions are recognised and not booked twice, and an auto-match assistant pairs bank lines with entries already in the books.

Turn documents into entries (AI drafting). Paste in an invoice, receipt or statement and the system proposes a complete double-entry, with its confidence, its reasoning, and the source text it worked from all visible. These are proposals only: accepting one creates an ordinary draft that still has to be submitted, approved and posted, and it must be approved by someone other than whoever accepted it. Rejected drafts are kept, because they are the record of what the model got wrong.

Work the journal when needed (Journals). The journal is the formal list of accounting entries. Each entry moves through a clear workflow — draft → pending review → approved → posted — and only posted entries are part of the permanent ledger. AI-drafted entries appear in pending review, waiting for a person. Drafts need not balance; posting is the step that insists.

Posted means permanent. A posted entry can never be edited or deleted — by anyone. If it's wrong, you post a reversal: a mirror-image entry that cancels it, leaving both visible. This is not a limitation; it is what makes the books trustworthy. Expect it, and don't look for an edit button.

Handle invoices and bills (Invoices, Payments). Raise sales invoices and record supplier bills; issuing one automatically writes the correct entry to the books — no manual journal work for everyday trading. Recording payments moves each document through issued → partially paid → paid, and a payment can be applied to a document or unapplied again. The AR/AP aging screen shows what's overdue, by how long, per customer and supplier.

Check the numbers (Trial balance, Statements). The trial balance proves the books tie — total debits equal total credits, to the cent. The statements screen produces the income statement, balance sheet, and cash flow for any period, and every line can be drilled down to the exact entries behind it.

And as your needs grow: Revenue recognition for contracts earned over time, Consolidation for a group of companies, Intelligence for the operating measures, Variance analysis to see what moved between two periods, Ask the ledger for plain-language questions, Exports to get your data out, and Audit trail for the permanent history of who did what, and when.

8. Weekly, monthly, and long-term duties

Software keeps the books; people keep the discipline. Here is the rhythm that keeps an installation healthy:

Regularly (weekly or as activity warrants)

• Review and clear the bank transaction queue — books are most useful when they're current.
• Reconcile: confirm the bank's records and your books agree (the auto-match assistant does the heavy lifting; you confirm).
• Clear anything sitting in pending review, so nothing waits on a decision nobody remembers owing.

Each period (typically monthly)

• Finish recording everything for the period, then close the period (Periods). Closing locks it: nothing further can be posted into a closed period, which is what makes your reported numbers final. A period can be reopened by an authorised person if something must be corrected before the books are truly final.
• Run and keep the period's reports — trial balance, income statement, balance sheet — as your record of the period. Producing the statements is also what makes Variance analysis able to compare that period later.
• If you recognise revenue over time, run recognition for the period (Revenue recognition). Running it twice is safe — rows already recognised are skipped.
• Check Tax alerts and act on anything raised.

Occasionally / long-term

• Back up your data — this is yours to own. On a self-hosted installation, no one else is backing up your database. Put a regular backup in place, know how to restore it, and always take a backup before anything destructive (like re-initialization). If data is lost without a backup, there is no way back.
• Keep tax rates current (Tax rates). When your jurisdiction changes a rate, update it here. The alerts screen will tell you when a rate you are still using has passed its end date, but it does not watch legislation on your behalf — see section 10.
• Keep exchange rates up to date if you trade in more than one currency.
• Review who has access (Members) as people join and leave, and keep roles as small as jobs allow.
• Leave history alone. The audit trail and posted entries are permanent by design. There is no periodic "cleanup" of financial history in this system — and that's a feature, not an oversight. The only operations that destroy data are demo expiry and re-initialization.
• Start the next financial year when one ends, so new periods exist to post into.

9. The demo data, and starting fresh

The preview and demo versions arrive with a complete, fictional dataset already loaded, so every screen has something real to show. It contains three made-up companies:

• Northwind Trading Co. — a US company reporting under GAAP in US dollars. This is the one the tour is told from.
• Northwind Logistics Inc. — its subsidiary, also US and GAAP. The two together are what make the Consolidation screen meaningful, including a deliberate small disagreement between them so you can see how the software reports one.
• Lumière Studio — a German company reporting under IFRS in euros, so that the other rulebook and a second currency are both represented.

Between them they carry a full chart of accounts, posted journal entries at every stage of the workflow, customer invoices and supplier bills, payments, bank transactions with AI suggestions already attached, revenue contracts with schedules, generated financial statements, and a populated audit trail.

None of it is yours, and none of it should be kept. When you want to work with real books, do not clear the sample data out of a demo — start a proper installation instead, following production-initialization.md. That is the only supported route to a clean, real set of books.

If you are running the downloadable preview on your own machine, it keeps nothing between runs by default: stop it and start it again and you get a pristine copy of the sample data back. The preview's own notes explain how to attach storage if you want your changes to survive a restart, and how to stop it reloading the sample data over them.

10. Common questions and gotchas

"I made a mistake — where is the edit button?" There isn't one, and that is deliberate. Anything still in draft can be edited freely. Once an entry is posted it is permanent; correct it by posting a reversal. See section 7.

"The Ask-the-ledger screen says questions cannot be answered." That feature needs a language-model provider configured for your installation, and the downloadable preview deliberately reaches no outside service, so it has none. Everything else works without one; the same figures are available on the Statements, Trial balance and AR/AP aging screens. Ask whoever operates your installation to configure a provider.

"Variance analysis says there is nothing to compare." That screen reads the financial statements you have already produced rather than recalculating them. Generate the statements for both periods on the Statements screen first, then come back.

"Why does the AI's suggestion get ignored?" Your own coding rules are checked before the model, and the first matching rule decides. That is the intended order — look in Coding rules if a suggestion is not what you expected.

"Am I protected from a tax change I haven't heard about?" No. Tax alerts are raised from your own rates and your own documents — for example, a rate still selectable after its window has closed. Nothing in the software watches legislation for you, and it says so on the screen.

"An export refused to produce a file." That is the intended behaviour. Where a format requires something you have not recorded, the export stops and names what is missing rather than producing a file with an invented or blank value in it.

"The books show a figure I don't believe." Every statement line drills down to the entries behind it, every intelligence measure shows its formula and the accounts it used, and the audit trail records every change with its before-and-after. Follow it back; the answer is always recorded.

"Can we use this commercially, or build our own product on it?" Yes, to both. The software is licensed Apache-2.0: you may use it in your business, modify it, and build and sell products derived from it, including closed-source ones. You do not have to publish your changes. The one obligation is attribution — a short notice crediting WBSP has to travel with anything you redistribute, which you satisfy by keeping the NOTICE file, or by carrying its text in your own documentation or wherever your product lists third-party notices. The full terms are in the LICENSE file at the top of the project.

"Can more than one company share an installation?" Yes. One installation can host several organisations, and one person can belong to several with a different role in each. Creating an additional organisation is an administrator action.

11. Glossary

Plain words for every term this document uses.

Term	In plain words
Accounts payable (AP)	Money your business owes to suppliers — bills you haven't paid yet
Accounts receivable (AR)	Money customers owe your business — invoices they haven't paid yet
AI confidence	How sure the AI is about a suggestion, shown as a percentage and a high/medium/low band
API	A documented way for one program to talk to another — how integrators connect this software to other systems
Audit trail	The permanent, unchangeable log of who did what in the system, and when
Balance sheet	The report showing what the business owns, owes, and is worth at a point in time
Bank feed	A live connection to your bank that brings transactions in automatically
Base currency	Your organisation's home currency; amounts in other currencies are also carried in this one
Burn / runway	How fast the business is consuming cash, and how long the cash on hand will last at that rate
Chart of accounts	The organised list of labelled "buckets" every transaction is filed into
Coding rule	Your own instruction that a bank line matching a pattern always goes to a chosen account
Consolidation	Combining several companies in a group into one set of figures, with dealings between them removed
CSV / OFX	Common file formats banks use for exported statements; you can upload either
Debit / credit	The two sides of every double-entry record; for every transaction they must add up equally
Deferred revenue	Money received or invoiced for work not yet done, so not yet counted as earned
Double-entry	The bookkeeping method where every event is recorded in two places so the books always balance
E-invoice	An invoice in a standard machine-readable format that your customer's system can process directly
Elimination	Removing a dealing between two companies in the same group, so the group isn't counted as trading with itself
Fiscal (financial) period	A slice of the financial year — usually a month — that entries are posted into and reported on
GAAP / IFRS	The two major rulebooks for how accounts are prepared (US / most of the rest of the world)
General ledger	The master record containing every posted accounting entry — "the books"
Income statement	The report of money earned and spent over a period — also called profit and loss (P&L)
Journal entry	One recorded accounting event, made of balancing debit and credit lines
Material (movement)	A change big enough to be worth attention, judged by both its size and its percentage
Apache-2.0	This project's licence — permissive: commercial use, changes and closed derivatives are all allowed, and crediting WBSP is what is asked in return
Open source	Software whose full program code is public and free to use, inspect, and modify
Performance obligation	A distinct promise in a contract; revenue is earned as each one is satisfied
Period close	Locking a finished period so nothing more can be posted into it — making its numbers final
Posting	The act of making an entry part of the permanent ledger; posted entries can only be reversed, never edited
Reconciliation	Confirming your books and your bank's records agree, item by item
Revenue recognition	Counting income in the period it is actually earned, rather than when it is invoiced or paid
Reversal	A mirror-image entry that cancels a wrong posted entry, leaving both visible
Role	What a signed-in person may do: owner, admin, accountant, bookkeeper, or viewer
Self-hosted	Run on computers your organisation controls, rather than a vendor's cloud
Trial balance	The check-report proving total debits equal total credits across all accounts
Variance analysis	Comparing one period against another to see what changed, and by how much

12. The other documents, and where to get help

Everything else that ships with the project, and who each piece is for:

For everyone

• getting-started.md — a shorter, more hands-on start than this document: get the software running and complete your first real tasks.
• production-initialization.md — the step-by-step procedure for standing up a real installation: the safeguards, exactly what gets created, and how the first owner is linked to their login. Read this before any real use.

For developers and integrators

• api-reference.md — how to drive the software from other programs, in prose.
• openapi.yaml — the same interface as a formal specification file, for tools that generate code from it.
• mcp-server.md — how to connect an AI assistant directly to the books, so it can answer questions and carry out tasks against your own data.
• testing.md — how the software is tested, and how to run those tests yourself.
• useful-commands.md — the day-to-day commands for running and operating the software.

About the project as a whole

• README — the feature overview and project background.

Where to get help. This application is one of many built by the community at wbsp.ai. That is the place to go for more information, to suggest what this software should do next, or to be put in touch with people who can adapt it to your business. It is also worth browsing: community members have built other versions of this application and a great many others, and one of them may already be close to what you need.