ekwo-os 0.4.1 → 0.5.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,8 +265,10 @@ 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 doc list` / `show` | What exists, and with `--unpaid` what is posted and still owed. See [keeping books](#keeping-books). |
@@ -280,6 +284,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 +431,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 +448,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 +466,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 +491,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`,
@@ -637,12 +647,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 +740,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 +749,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`.