ekwo-os 0.4.1 → 0.6.0

package/README.md

@@ -112,8 +112,10 @@ the packs the database holds. A preselected country is a chart of accounts
 nobody chose.
 
 The same is true of the financial year: a pack that declares no usual opening
-month makes `--fiscal-year-start` required. Both packs shipped here open on the
-calendar year, so it rarely comes up.
+month makes `--fiscal-year-start` required. Most packs name the calendar year
+in `defaults.fiscal_year_default`; one that names none — the United Kingdom's,
+where a company's year ends on the accounting reference date it chose — asks
+for the day.
 
 ## Where table access comes from
 
@@ -158,7 +160,7 @@ migrations put the privileges back themselves, and they take away the blanket
 table access the project's defaults had handed `anon`. Dropping `public` is
 still not something to do on a project you intend to keep — it takes your books
 with it. The decision and what it changed are in
-[`docs/decisions.md`](../../docs/decisions.md).
+[decision 0003](../../docs/decisions/0003-the-schema-grants-its-own-rights.md).
 
 ## Before you go live: four things on your project
 
@@ -217,7 +219,7 @@ and read by a person.
 | Step | What happens | Why it is done this way |
 |---|---|---|
 | 1 | Applies `supabase/migrations/*.sql` in order | Recorded in `supabase_migrations.schema_migrations`, the Supabase CLI's own history table, so `supabase db push` and `ekwo migrate` stay interchangeable |
-| 2 | Applies the six reference seeds, in file-name order: `00_currencies.sql`, `05_framework_generic.sql`, `10_pack_be.sql`, `11_pack_fr.sql`, `12_pack_lu.sql`, `13_pack_ee.sql` | The currencies, the country-less financial statements every chart falls back on, and the four country packs. They are exactly the six `supabase/config.toml` lists, so `supabase db push` installs the same set; a test compares both paths row by row. `90_demo_company.sql` is sample data and is never applied here |
+| 2 | Applies every reference seed of `supabase/seed/`, in file-name order: `00_currencies.sql`, `00_territories.sql`, `05_framework_generic.sql`, then one `<n>_pack_<cc>.sql` per country pack, in the order of the number each pack declares | The currencies, the territories the tax rules name, the country-less financial statements every chart falls back on, and every country pack of the release — so a company in any of them can be created later without installing anything. They are exactly the seeds `supabase/config.toml` lists (a list `ekwo pack build` writes from `packs/`), so `supabase db push` installs the same set; a test compares both paths row by row. `90_demo_company.sql` is sample data and is never applied here |
 | 3 | Creates the first administrator through the Supabase Auth admin API | See below: a database connection cannot be a signed-in user |
 | 4 | `init_instance()`, `claim_instance_admin()`, the company, `company_members` as owner, `install_country_template()`, the first financial year, and the bank account when an IBAN was given | The six steps of the root README, in the same order, plus the one thing nobody can derive |
 | 5 | Writes `ekwo.json` | Project URL, country, schema version. Nothing else, ever |
@@ -248,7 +250,7 @@ instead if the account already exists, and no key is needed.
 
 | Command | What it does |
 |---|---|
-| `ekwo init` | The whole installation, interactive or not. |
+| `ekwo init` | The whole installation, interactive or not: the socle's migrations, the reference seeds, then the modules', as `ekwo migrate` applies them. |
 | `ekwo migrate` | Applies the migrations this release adds, after showing the gap — the socle's, then the modules'. Re-applies the reference seeds, which are idempotent. `--no-modules` leaves the modules alone. |
 | `ekwo status` | Schema version installed against available, pending migrations, the instance, its administrators, the country packs it holds and, per company, the pack version it copied. Exits 1 when something is pending. |
 | `ekwo doctor` | Every object this release defines and every privilege it grants, against what the database holds; row level security on every table, a policy on every protected table, no pending migration, no membership pointing at a deleted user, every company with a bank account, statements that tie to their lines, posted entries that balance. Exits 1 on a problem, 0 on warnings. |
@@ -263,10 +265,13 @@ instead if the account already exists, and no key is needed.
 | `ekwo use <company>` | Picks the company the next commands run on. |
 | `ekwo whoami` | Who you are on which instance, the companies you can see, and what you may do on the one in use. |
 | `ekwo contact add` / `list` | A customer or a supplier, and finding one again. |
-| `ekwo invoice new` / `invoice line add` | A draft document — any kind, with `--type` — and one more line on it. A draft books nothing. |
+| `ekwo doc new` / `doc line add` | A draft document — any kind, with `--type` — and one more line on it. A draft books nothing. `ekwo invoice` is the old name of `ekwo doc`, kept as an alias. |
 | `ekwo post <document>` | Books it, through `post_document()`. `--dry-run` shows the entry the database would write and writes nothing. |
+| `ekwo cancel <document>` | Undoes a posted invoice, and says how. Back to draft, through `unpost_document()`, where its country allows it and nothing about it has left; otherwise through `cancel_document()`: the credit note that names it, posted and matched against it, and the invoice cancelled. `--date` books the credit note on another day than the invoice's, which is how a locked period is stepped over; `--credit` asks for the note where a draft was possible. |
+| `ekwo reverse <entry>` | Undoes a posted entry keyed by hand, through `reverse_entry()`: its mirror, posted and matched against it. By id or by number; `--date` as for `cancel`. |
 | `ekwo payment record` | Money in or out, booked and matched. With `--doc`, against that document. |
 | `ekwo match <transaction> <document>` | A bank statement line pays a document, through `settle_from_statement()`. |
+| `ekwo import <source> <file>…` | Books kept elsewhere — `trial-balance`, `fec`, `journal-items`, `journal-report` — whole or not at all, through `import_books()`, with a correspondence of accounts and journals you save and give back; or a bank statement — `camt.053`, `coda`, `cfonb120` — as pending lines. `--dry-run` rehearses. See [taking over books](#taking-over-books-ekwo-import). |
 | `ekwo doc list` / `show` | What exists, and with `--unpaid` what is posted and still owed. See [keeping books](#keeping-books). |
 
 There is no `eject`, because there is nothing to eject from. The schema is in
@@ -280,6 +285,10 @@ a terminal and never when `NO_COLOR` is set, no spinner and no line redrawn in
 place, so the output reads the same in a file or a CI log — and takes `--json`
 for a program.
 
+`ekwo help --json` answers the list of commands and, in `usage`, the whole
+text of `--help` without colour: every flag and variable, for an assistant
+that reads one document rather than a terminal.
+
 Under `--json` the standard output is **one JSON document and nothing else**;
 the prose still goes by, on the standard error. The document has the same
 shape whatever happened:
@@ -423,11 +432,12 @@ them as it reads a driver's.
 
 ```bash
 ekwo contact add "Client Example" --country <cc> --ref crm-42
-ekwo invoice new --contact client --date 2026-06-15 --ref job-7 \
+ekwo doc new --contact client --date 2026-06-15 --ref job-7 \
      --line "name=Audit,price=1500.00,account=<account code>,tax=<tax code>"
-ekwo invoice line add job-7 --name Travel --price 250.00 --account <account code>
+ekwo doc line add job-7 --name Travel --price 250.00 --account <account code>
 ekwo post job-7 --dry-run        # the entry the database would write; nothing is written
 ekwo post job-7                  # post_document()
+ekwo cancel job-7                # back to draft where the country allows it, else the credit note
 ekwo payment record --doc job-7 --amount 1750.00 --date 2026-06-30 --bank-account <id> --ref bank-1
 ekwo match <bank transaction id> job-9
 ekwo doc list --unpaid --since 2026-06-01 --json
@@ -439,8 +449,9 @@ and none is ever picked for you: with no company in use a verb ends on
 
 **Each verb is one function, and it is not ours.** The functions live in
 `@ekwo-ai/core` and the MCP server calls the same ones: `contact add` is
-`create_contact`, `invoice new` is `create_document`, `post` is
-`post_document`, `payment record` is `record_payment`, `doc list` and
+`create_contact`, `doc new` is `create_document`, `post` is
+`post_document`, `cancel` is `unpost_document` or `cancel_document` — `unpost_refusal` chooses —, `reverse` is `reverse_entry`,
+`payment record` is `record_payment`, `doc list` and
 `doc show` are `list_documents` and `get_document`. Underneath them the rules
 are the schema's — the balance, the numbering, the locks, the taxes, the
 territory, the tax point. **This CLI computes no amount**: what you type goes
@@ -456,7 +467,7 @@ not a draft, a document with nothing open — is exit code 2: the call has to
 change.
 
 **`--ref`, so that nothing is created twice.** On what creates (`contact add`,
-`invoice new`, `payment record`), `--ref <your reference>` is kept on the row,
+`doc new`, `payment record`), `--ref <your reference>` is kept on the row,
 unique per company. The same reference a second time returns what the first
 call created, with `"replayed": true`, and writes nothing — and finishes what
 a dropped connection left half done: a draft whose lines never arrived, a
@@ -481,7 +492,7 @@ given beside it win.
 ```bash
 echo '{"contact":"client","document_date":"2026-06-15","client_ref":"job-8",
        "lines":[{"name":"Review, \"urgent\"","unit_price":"200.00","account_code":"<code>"}]}' \
-  | ekwo invoice new --stdin --json
+  | ekwo doc new --stdin --json
 ```
 
 **`--line`, for a person.** Named fields, never positions: `name`, `price`,
@@ -496,6 +507,100 @@ Two values are supplied when nobody gives them, and said when they are:
 `--type` is `sale_invoice`, and `--date` is today on the machine running the
 command. Whether that date may be booked on is the database's decision.
 
+## Taking over books: `ekwo import`
+
+To try Ekwo on your own books, bring them. One command, one reader per
+source, and nothing is posted while an account has no answer:
+
+```bash
+ekwo import fec 123456789FEC20251231.txt --dry-run --open-years --save-mapping map.json
+#   read, propose a correspondence, rehearse the import in the database, take it back
+$EDITOR map.json                                   # answer what is null, correct what is wrong
+ekwo import fec 123456789FEC20251231.txt --mapping map.json --open-years
+ekwo import trial-balance balance.csv --opening-date 2026-01-01 --dry-run --save-mapping map.json
+ekwo import journal-items items.csv accounts.csv partners.csv --dry-run --save-mapping map.json
+ekwo import journal-report report.csv chart.csv --date-order dmy --dry-run --save-mapping map.json
+ekwo import camt.053 statement.xml                 # or coda, cfonb120: pending lines for `ekwo match`
+```
+
+| Source | What it reads |
+|---|---|
+| `trial-balance` | A trial balance as CSV — `account`, `debit`, `credit`, or one signed `balance` — which becomes the opening entry of the year `--opening-date` starts |
+| `fec` | A *fichier des écritures comptables*: the eighteen columns of the arrêté of 29 July 2013, tab or bar separated |
+| `journal-items` | The lines of every entry exported as CSV from the list view of an ERP whose ledger is a table of lines, with the chart of accounts and the partners exported beside it |
+| `journal-report` | A journal report or a general ledger detail, saved as CSV from a cloud service's spreadsheet export, with its Journal ID and Account Code columns, and the chart and the contacts beside it |
+| `camt.053`, `coda`, `cfonb120` | A bank statement: its lines, pending, ready for `ekwo match` |
+
+Each reader is a brick of [`packages/formats/`](../formats/README.md), named
+after the file; its README says which columns it reads and which official
+pages the format was read from. The exports of other ledgers can also be named
+by the software they come from: `ekwo import --help` lists those names, and
+[`docs/compatibility.md`](../../docs/compatibility.md) gives each one's export,
+official page and state.
+
+**The correspondence is yours.** Every account of the old chart has to become
+an account of the company's chart, and every old journal a journal of the
+company. The core proposes, from the codes alone — the same code, the same
+digits without the zeros a chart pads with (`411` and `411000`), or the
+account whose digits are the longest beginning of the old code, three at least
+(`401ACME` → `401000`); a tie is no answer — and each proposal says which rule
+found it. `--save-mapping` writes it as JSON:
+
+```json
+{
+  "version": 1,
+  "source": "fec",
+  "accounts": { "411000": "411000", "401ACME": "401000", "471200": null },
+  "journals": { "VE": "SAL", "AN": "@opening", "BQ1": "MISC" }
+}
+```
+
+and `--mapping` gives it back: what it answers wins over the proposal, so the
+second run posts what the first one showed. A journal mapped to `@opening`
+becomes the opening entry of its year instead of ordinary entries — the
+*à-nouveaux* of a FEC, typically. A journal whose code is the one the pack
+opens years on is proposed as `@opening` on its own; `*` stands for entries
+the source gives no journal.
+
+**Whole or not at all.** `import_books()` is one call and one transaction: the
+fiscal years it needs (with `--open-years`, as years of the same length and
+first day as the company's own; without, an entry outside every year is
+refused by name), the parties the lines name — found by their code or their
+name, or created as customers or suppliers according to where their lines are
+booked — every entry as a draft then posted by `post_entry()`, and the opening
+through `opening_balance()`. One refusal — a locked period, an account the
+chart does not have, a capability you do not hold — and nothing stays, not
+even the years or the parties.
+
+**`--dry-run` is the real thing, taken back.** The database runs the whole
+import and rolls it back, so the numbers shown are the ones the entries would
+take now and a refusal is the one the import would give. For a bank statement a
+dry run reads the file and asks nothing: a statement books nothing anyway.
+
+What else to know:
+
+- **Refused before the database is asked**, and listed under `refusals` by a
+  dry run: an account or a journal with no answer, books whose reader found
+  something that does not add up (an entry that does not balance, a line of a
+  draft entry), a currency the files name that is not the company's.
+- **The numbers** are drawn by the journal each entry goes to; the old number
+  is kept as the entry's reference. `--keep-numbers` posts each under its old
+  number instead, where the country allows a number chosen by hand or you hold
+  `entries.import`.
+- **No tax.** An imported line carries an account and an amount, not the tax
+  that produced it: the history feeds the ledger, the trial balance and the
+  statements, and no box of a VAT return. A period kept elsewhere was declared
+  from where it was kept.
+- **The same files twice are refused** (`import_already_done`): `book_imports`
+  keeps the checksum of what each import read.
+- **Dates and encodings are said, never guessed**: `--encoding` for a file
+  that is not UTF-8, `--date-order` for a report that writes dates in digits.
+- **Reconciliation marks are read and not re-applied yet**: the matching of an
+  imported receivable against its payment is done in Ekwo, with `reconcile`.
+
+The MCP server offers the same as `import_books`, and `import_bank_statement`
+for a statement. [`docs/import.md`](../../docs/import.md) is the long form.
+
 ## `ekwo module`
 
 A module is a Postgres schema beside the socle — `assets` for fixed assets,
@@ -637,12 +742,38 @@ migration runner and by nothing else.
 
 ```sh
 ekwo pack list           # the packs this checkout carries, and their certification
-ekwo pack build be       # write supabase/seed/10_pack_be.sql from packs/be
+ekwo pack describe       # everything each of them says; one country with `describe <cc>`
+ekwo pack build be       # write supabase/seed/10_pack_be.sql from packs/be, and the lists of packs
 ekwo pack build --all
-ekwo pack check be       # validate one pack and compare its seed
-ekwo pack check --all    # exit 1 if a committed seed is not the output of its pack
+ekwo pack check be       # validate one pack, compare its seed and the lists of packs
+ekwo pack check --all    # exit 1 if a committed seed or list is not the output of the packs
 ```
 
+The lists are the blocks of other files that name every pack — the seeds of
+`supabase/config.toml` and of the root README, the `/packs/<cc>/` lines of
+`.github/CODEOWNERS`, the table of `docs/packs.md` — each between a
+`generated:<name>` marker and `/generated`. They are written from `packs/` the
+way a seed is, so a country is added in `packs/<cc>/` and nowhere else.
+
+`list` is a line per country. `describe` is the whole of one: the charts and
+who each is published for, the taxes and their distinct rates, the periodic
+declaration with its cadences and its boxes, whether the country states a rule
+for when the return is due, the brick that writes the file it is deposited as
+or that it is filed by hand on a portal, the e-invoicing profile and the day it
+starts, the accounts the tax balance lands on, every bank statement format the
+country names and whether anything here reads it, the financial statements, and
+the texts the pack was built from with the day each was last opened. Every
+answer is read from the pack, and a "not yet" is printed rather than left out.
+
+```sh
+ekwo pack describe --json | jq '.data.packs[] | {country, version}'
+```
+
+Under `--json` the whole description of every pack is the result. It is the
+same object the site at [ekwo.ai](https://ekwo.ai/countries/) builds each
+country's page from, so the site and the command line cannot come to say
+different things about a country.
+
 `check` validates every file of the pack against
 [`packs/schema/pack.1.json`](../../packs/schema/pack.1.json) and against the
 rest of the pack, then compares the committed seed with what the compiler makes
@@ -704,8 +835,8 @@ dashboard under Connect → Session pooler, is the form that is never derived.
 | `--admin-password <pw>` | Their password. Omitted, an invite link is generated and printed. |
 | `--admin-user-id <uuid>` | Use an account that already exists, instead of creating one. |
 | `--fiscal-year <year>` | Calendar year of the first financial year. Defaults to this year. |
-| `--fiscal-year-start <date>` | The day that year opens, as `YYYY-MM-DD`. Needed only where the pack names no usual opening month; the two packs shipped both open on the calendar year. |
-| `--currency <code>` | Currency of the company. Defaults to what the country model says: `EUR` for both countries shipped. |
+| `--fiscal-year-start <date>` | The day that year opens, as `YYYY-MM-DD`. Needed only where the pack names no usual opening month (`defaults.fiscal_year_default`). |
+| `--currency <code>` | Currency of the company. Defaults to the pack's `defaults.currency`. |
 | `--language <xx>` | Language of the books, two letters. Defaults to `country_defaults.language_default`, which the pack fills. It decides which label of the pack lands on each account; the others are kept in `name_i18n`. |
 | `--iban <iban>` | Creates the main bank account, wired to the bank journal and its ledger account. Omitted, no bank account is created and `ekwo doctor` says so. |
 | `--bic <bic>` | Optional, on that account. |
@@ -713,6 +844,7 @@ dashboard under Connect → Session pooler, is the form that is never derived.
 | `--demo` | Also load the sample company. |
 | `--register` | Register without being asked. `--register-email` sets the address. |
 | `--registry-url <url>` | Where the registration is announced. |
+| `--no-modules` | Leave the modules out. By default `init` installs them, as `ekwo migrate` does — empty schemas until a company enables one. |
 
 Every command takes `--json`; see [what a command answers](#what-a-command-answers---json-and-the-exit-codes).
 `ekwo migrate` takes `--skip-seeds`.