kotsu-cli 0.1.0__tar.gz → 0.1.1__tar.gz

kotsu_cli-0.1.0/.github/workflows/verificar.yml → kotsu_cli-0.1.1/.github/workflows/check.yml

@@ -1,11 +1,11 @@
-name: verificar
+name: check
 
 on:
   push:
   pull_request:
 
 jobs:
-  verificar:
+  check:
     strategy:
       fail-fast: false
       matrix:
@@ -18,6 +18,6 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
       - run: python -m pip install -e ".[dev]"
-      - run: python ferramentas/verificar.py
+      - run: python tools/check.py
       - run: python -m pip install pipx
-      - run: python ferramentas/testar_instalacao.py
+      - run: python tools/check_install.py

kotsu_cli-0.1.0/.github/workflows/publicar.yml → kotsu_cli-0.1.1/.github/workflows/publish.yml

@@ -1,32 +1,32 @@
-name: publicar
+name: publish
 
-# Publica no PyPI quando uma tag v* (ex.: v0.1.0) é enviada. Usa Trusted Publishing: sem token.
+# Publishes to PyPI when a v* tag (e.g. v0.1.0) is pushed. Uses Trusted Publishing: no token.
 on:
   push:
     tags: ["v*"]
 
 jobs:
-  construir:
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - name: Confere a versão da tag
+      - name: Check the tag version
         run: |
           v=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
-          test "v$v" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != versão $v"; exit 1; }
+          test "v$v" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != version $v"; exit 1; }
       - run: pip install -e ".[dev]" build
-      - run: python ferramentas/verificar.py
+      - run: python tools/check.py
       - run: python -m build
       - uses: actions/upload-artifact@v4
         with:
           name: dist
           path: dist/
 
-  publicar:
-    needs: construir
+  publish:
+    needs: build
     runs-on: ubuntu-latest
     environment: pypi
     permissions:

{kotsu_cli-0.1.0 → kotsu_cli-0.1.1}/.gitignore

@@ -7,17 +7,19 @@ dist/
 .venv/
 venv/
 
-# Ferramentas
+# Tools
 .pytest_cache/
 .ruff_cache/
 .coverage
 htmlcov/
 
-# Dados pessoais: nunca versionar bancos, backups ou exports
+# Personal data: never version databases, backups or exports
 *.sqlite
 *.sqlite3
 *.sqlite-*
 *.sqlite3-*
+*.mcv
+*.mcp
 *.db
 *.db-journal
 *.db-wal
@@ -26,7 +28,7 @@ backups/
 *.csv
 .env
 
-# Editores e sistema
+# Editors and system
 .vscode/
 .idea/
 .DS_Store

kotsu_cli-0.1.1/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md
+
+Guide for anyone changing this repository, person or agent. Read it before changing code.
+
+## What it is
+
+Kotsu: a terminal app (Python + Textual) for the month's income, expenses, categories,
+accounts and installments. Main target: Windows Terminal, working the same on Linux.
+
+## Commands
+
+```bash
+pip install -e ".[dev]"
+kotsu --data ./tmp                   # opens the app with a test folder
+python tools/check.py --quick        # before every commit
+python tools/check.py                # before every PR (same as CI)
+python tools/layers.py               # only the layers rule
+python tools/check_install.py        # pipx install; uses the network only to install
+python tools/generate_vectors.py     # rewrites vectors/*.json (Android cases)
+```
+
+## Layers (the test fails if they are broken)
+
+| Folder | May import | Must not |
+|---|---|---|
+| `src/kotsu/domain/` | only the standard library without I/O | `storage`, `ui`, `sqlite3`, `os`, `pathlib`, `io`, Textual, Rich |
+| `src/kotsu/storage/` | `domain` | `ui`, Textual, Rich |
+| `src/kotsu/ui/` | `domain`, `storage` | `sqlite3` directly |
+
+`src/kotsu/__main__.py` is the assembly point and may see everything.
+Financial rules (totals, installments, quick-line parser) live in `domain/`; the UI only shows.
+
+## Data rules
+
+- Money is an `int` in cents, always positive; the sign comes from `kind` (income/expense).
+  Never `float`.
+- Every entry has an account (D21): the domain and the database refuse an entry without one.
+  The category is optional.
+- Dates are calendar dates (`datetime.date`), no time zone, stored as `YYYY-MM-DD`.
+- Totals (income, expenses, balance) are never stored: SQL computes them per month.
+- Month queries use the range `date >= start AND date < end` so the index is used.
+  Lists are paginated (`limit`, `offset`).
+- On screen, a negative amount shows only in red, without a sign (`domain.money.format_cents`).
+- Amounts are typed and shown in the Brazilian format (`1.234,56`) and dates as `dd/mm/yyyy`;
+  everything else (code, UI text, docs) is in English.
+
+## Database and migrations
+
+- Every write goes through `Database.transaction()`: all or nothing. The installments of a
+  purchase go in a single transaction.
+- Schema changed? Create `src/kotsu/storage/migrations/NNNN_name.sql` with the next number.
+  Never edit a published migration. Before migrating an existing database, the app copies the
+  file to `money.before-vN.sqlite`.
+- Test every new migration with a database at the previous version.
+- Migrations 0001 to 0003 still use the original Portuguese table names; 0004 renames
+  everything to English (and `receita`/`despesa` to `income`/`expense`).
+- Recurrence (D36): `recurring` category + `recurrence` table (series template and
+  `generated_until`). `Database.extend_recurrences(month)` generates the missing months and
+  only moves forward, so a deleted month does not come back. The UI calls it when drawing,
+  limited to today + 24 months.
+- Backup is manual only (D35): key `b` copies the database to `backups/` with date and time in
+  the name, without overwriting, and keeps only the 5 most recent (pruned after publishing).
+  The app never backs up on its own. Test clock and failures with temporary data. In-memory
+  (`Database.in_memory()`) makes no backup.
+
+## Exchange between devices (D39)
+
+- Each device has its own database; data is joined through an exchange file
+  (`--export`, `--import`, `--verify`). The merge rule is pure and lives in
+  `domain/merge.py`; reading, writing and applying live in `storage/exchange.py`.
+- Every write to `account`, `category`, `entry` and the `recurrence` template stamps
+  `changed_at` with `Database.stamp(c)` (one stamp per transaction). Editing an entry clears
+  `generated`. Deleting an entry writes the tombstone before the `DELETE`. Forgot the stamp?
+  The change loses to the other device on merge.
+- Advancing `generated_until` does not stamp: the generated month uses the fixed `uid`
+  (`month_uid`) and the series template's stamp.
+- A new field in a synced table goes into: the migration, `exchange.read_state`,
+  `exchange._apply`, `merge.validate`, the canonical form (changes the check code) and
+  `FORMAT` if old files stop working. Format 1 files (Portuguese keys) are translated by
+  `merge.upgrade_v1`.
+- `vectors/*.json` are the cases shared with the Android app. Changed a domain rule
+  (quick line, dates, money, stamp, merge)? Add the case in `tools/generate_vectors.py`, run
+  it and review the JSON diff. The test fails if the files are out of date.
+
+## Compatibility with the Portuguese versions
+
+Installed copies from before the English rename keep working after updating:
+
+- Old flags (`--dados`, `--pasta-dados`, `--pasta-dados-padrao`, `--forcar`, `--exportar`,
+  `--importar`, `--conferir`) are still accepted, hidden from `--help`.
+- `MONEY_CLI_DADOS` still works next to `KOTSU_DATA`; the `money` command still exists.
+- The local folder `money-cli` is renamed to `kotsu`; `pasta_dados` in `local.toml` is read.
+- `tema.toml` is read and replaced by `theme.toml`; old theme names map to the new ones.
+- `kotsu.trava` from a computer not updated yet still blocks; the new lock is `kotsu.lock`.
+- Dialog keys from before (`s`, `t`, `p`) still work next to the English ones.
+
+## How to work
+
+- Everything in English: code, messages, UI text, documents and file names.
+- New or changed product decision: describe it in the PR and update the README in the same PR.
+- Nothing goes into `main` without the maintainer's approval. Work on a branch and open a PR.
+- Tests use neither the network nor the real data folder (use `Database.in_memory()` or
+  `tmp_path`).
+- The README and this file are updated in the same PR that changes what they describe.
+- Fixed palette in `ui/colors.py`; change it little and on purpose.
+- Never version databases, backups or exports (`.gitignore` blocks SQLite, `*.mcv`, `*.mcp`
+  and `*.csv`).
+- Real install tests via pipx run outside the checkout on Windows/Linux CI; they need the
+  network only to install. Unit tests stay offline.
+- Commits with the GitHub noreply e-mail, fully in English.

{kotsu_cli-0.1.0 → kotsu_cli-0.1.1}/PKG-INFO

@@ -1,10 +1,9 @@
 Metadata-Version: 2.5
 Name: kotsu-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Cozy personal finance in your terminal: income, expenses and installments of the month on one screen.
 Project-URL: Homepage, https://github.com/Sera-DAI/kotsu
 Project-URL: Issues, https://github.com/Sera-DAI/kotsu/issues
-Project-URL: Português, https://github.com/Sera-DAI/kotsu/blob/main/README.pt-BR.md
 Author: Sera-DAI
 License-Expression: MIT
 License-File: LICENSE
@@ -23,11 +22,9 @@ Requires-Dist: ruff>=0.6; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/banner.en.svg" alt="Kotsu: cozy personal finance in your terminal" width="100%">
+  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/banner.svg" alt="Kotsu: cozy personal finance in your terminal" width="100%">
 </p>
 
-<p align="center"><b>English</b> · <a href="https://github.com/Sera-DAI/kotsu/blob/main/README.pt-BR.md">Português (Brasil)</a></p>
-
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-ff7fb8?style=flat-square&labelColor=1d1424&logo=python&logoColor=ffe9f4" alt="Python 3.11+">
   <img src="https://img.shields.io/badge/terminal-Windows%20%C2%B7%20Linux-ff7fb8?style=flat-square&labelColor=1d1424&logo=windowsterminal&logoColor=ffe9f4" alt="Windows Terminal and Linux">
@@ -36,14 +33,14 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/stack/python.svg" width="44" alt="Python" title="Python">
-  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/stack/githubactions.svg" width="44" alt="GitHub Actions" title="GitHub Actions">
-  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/stack/claude.svg" width="44" alt="Claude" title="Claude">
+  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/stack/python.svg" width="44" alt="Python" title="Python">
+  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/stack/githubactions.svg" width="44" alt="GitHub Actions" title="GitHub Actions">
+  <img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/stack/claude.svg" width="44" alt="Claude" title="Claude">
 </p>
 
 <p align="center"><sub>Built with Python, Textual, SQLite and Claude</sub></p>
 
-<p align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/divisor.svg" width="420" alt=""></p>
+<p align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/divider.svg" width="420" alt=""></p>
 
 # Kotsu
 
@@ -51,43 +48,42 @@ Description-Content-Type: text/markdown
 
 It runs on Windows Terminal and Linux, works offline and keeps everything in a SQLite file on your computer. No account, no cloud, no telemetry, no ads.
 
-> The app interface is in Brazilian Portuguese for now (labels such as *receitas* = income, *despesas* = expenses, *saldo* = balance). The commands and keys below work the same in any language.
-
 ## Contents
 
 - [I. What it does](#i-what-it-does)
 - [II. Install](#ii-install)
 - [III. Use](#iii-use)
 - [IV. Your data and backups](#iv-your-data-and-backups)
-- [V. Under the hood](#v-under-the-hood)
-- [VI. Development](#vi-development)
-- [VII. License](#vii-license)
+- [V. Updating from a Portuguese version](#v-updating-from-a-portuguese-version)
+- [VI. Under the hood](#vi-under-the-hood)
+- [VII. Development](#vii-development)
+- [VIII. License](#viii-license)
 
 ## I. What it does
 
 <table>
   <tr>
-    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/lancar.svg" width="44" alt=""></td>
-    <td><b>Quick line</b><br><code>89,90 mercado #alimentação @nubank</code> and Enter. No forms: the amount comes first, then account, category and date in any order.</td>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/add-entry.svg" width="44" alt=""></td>
+    <td><b>Quick line</b><br><code>89,90 groceries #food @nubank</code> and Enter. No forms: the amount comes first, then account, category and date in any order.</td>
   </tr>
   <tr>
-    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/parcelas.svg" width="44" alt=""></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/installments.svg" width="44" alt=""></td>
     <td><b>One screen</b><br>Income, expenses and balance for the month, one line per account (each with its own color) and the list of entries. The ← / → arrows switch months.</td>
   </tr>
   <tr>
-    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/todomes.svg" width="44" alt=""></td>
-    <td><b>Installments and "every month"</b><br><code>120 geladeira @nubank 10x</code> becomes 10 installments, one per month. Categories marked "every month" (rent, internet, salary) show up on their own, with a <code>↻</code>.</td>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/every-month.svg" width="44" alt=""></td>
+    <td><b>Installments and "every month"</b><br><code>120 fridge @nubank 10x</code> becomes 10 installments, one per month. Categories marked "every month" (rent, internet, salary) show up on their own, with a <code>↻</code>.</td>
   </tr>
   <tr>
-    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/temas.svg" width="44" alt=""></td>
-    <td><b>Two Cotton Candy themes</b><br>Night (default) and light, with hearts, a little face and "zzz… zerada" when an account is empty. The <code>t</code> key switches and your choice is saved.</td>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/themes.svg" width="44" alt=""></td>
+    <td><b>Two Cotton Candy themes</b><br>Night (default) and light, with hearts, a little face and "zzz… zeroed" when an account is empty. The <code>t</code> key switches and your choice is saved.</td>
   </tr>
   <tr>
-    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/teclado.svg" width="44" alt=""></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/keyboard.svg" width="44" alt=""></td>
     <td><b>Keyboard first</b><br>Everything has a key, and the footer reminds you which. Filter by <code>@account</code> or <code>#category</code> with <code>/</code>.</td>
   </tr>
   <tr>
-    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/privado.svg" width="44" alt=""></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/private.svg" width="44" alt=""></td>
     <td><b>Truly private</b><br>Your data stays on your computer. Kotsu never sends anything over the network.</td>
   </tr>
 </table>
@@ -96,21 +92,21 @@ It runs on Windows Terminal and Linux, works offline and keeps everything in a S
 
 <table>
   <tr>
-    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/instalar.svg" width="44" alt=""></td>
-    <td>Requires Python 3.11 or newer and <a href="https://pipx.pypa.io/">pipx</a>. The package is not on PyPI yet: install straight from GitHub.</td>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/install.svg" width="44" alt=""></td>
+    <td>Requires Python 3.11 or newer and <a href="https://pipx.pypa.io/">pipx</a>.</td>
   </tr>
 </table>
 
 Windows Terminal (PowerShell), in one line:
 
 ```powershell
-irm https://raw.githubusercontent.com/Sera-DAI/kotsu/main/instalar.ps1 | iex
+irm https://raw.githubusercontent.com/Sera-DAI/kotsu/main/install.ps1 | iex
 ```
 
 Linux/macOS (needs pipx; the script tells you if it is missing):
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Sera-DAI/kotsu/main/instalar.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Sera-DAI/kotsu/main/install.sh | bash
 ```
 
 Or step by step, without a script:
@@ -136,21 +132,21 @@ Reopen the terminal and run `kotsu`. To update: `pipx upgrade kotsu-cli` (or run
 ## III. Use
 
 ```text
- ☁ Algodão-Doce ☁   novembro de 2026
+ ☁ Cotton Candy ☁   November 2026
 
- ♡ receitas 3.500,00   ✧ despesas 432,90   ☆ saldo 3.067,10   (◕‿◕)♡
+ ♡ income 3.500,00   ✧ expenses 432,90   ☆ balance 3.067,10   (◕‿◕)♡
 
- ♡ itaú     ♥♥♥♥♥♥♥♥♥♥♥♥♥♥·    -210,50  +3.500,00
- ♡ nubank   ♥♥♥♥♥♥♥♥♥♥♥♥♥♥     -222,40
+ ♡ itaú     ♥♥♥♥♥♥♥♥♥·   income 3.500,00   expenses 210,50
+ ♡ nubank   ♥♥♥♥♥♥♥♥♥♥   income     0,00   expenses 222,40
 
- Data   Descrição   Categoria     Conta    Valor
- 08/11  padaria     alimentação   nubank   12,50
- 07/11  mercado     alimentação   nubank   89,90
+ Date   Description   Category   Account   Amount
+ 08/11  bakery        food       nubank    12,50
+ 07/11  groceries     food       nubank    89,90
 ```
 
 | Key | Action |
 |---|---|
-| `l` | opens the quick line (Enter saves, Esc closes) |
+| `l` | opens the quick line to log an entry (Enter saves, Esc closes) |
 | ← / → | previous / next month |
 | `/` | filters by `@account`, `#category`, both, or just a name (empty Enter or Esc clears) |
 | `e` | edits the selected entry in the quick line, date included |
@@ -166,29 +162,29 @@ Reopen the terminal and run `kotsu`. To update: `pipx upgrade kotsu-cli` (or run
 The line starts with the amount; the rest comes in any order:
 
 ```text
-89,90 mercado #alimentação @nubank     expense (no sign)
-+3500 salário @itaú                    income
-120 geladeira #casa @nubank 10x        10 installments of 120.00, one per month
-45 farmácia ontem                      date: ontem (yesterday), 15/10 or 15/10/2025 (default: today)
+89,90 groceries #food @nubank          expense (no sign)
++3500 salary @itau                     income
+120 fridge #home @nubank 10x           10 installments of 120,00, one per month
+45 pharmacy yesterday                  date: today, yesterday, 15/10 or 15/10/2025 (default: today)
 ```
 
-Every entry needs an `@account`; without one the line is not saved. An account or category that does not exist yet asks whether to create it. Editing or renaming an installment asks "only this one or all?". Amounts use a decimal comma and dates are day/month, as in Brazil.
+Every entry needs an `@account`; without one the line is not saved. An account or category that does not exist yet asks whether to create it. Editing or renaming an installment asks "only this one or all?" (`a` = all, `o` = only this). Amounts use a decimal comma and dates are day/month, as in Brazil.
 
 ### ↻ Categories that repeat every month
 
-When you create a category, Kotsu asks whether it repeats every month (or press `m` on an existing one). Every new entry in it reappears each month with the same amount, account and day (day 31 becomes the last day of the month), with no end, until you stop it. Months appear as you navigate with ← / →, up to 24 months ahead of today. Deleting, editing or renaming one asks "only this month or the following ones?".
+When you create a category, Kotsu asks whether it repeats every month (or press `m` on an existing one). Every new entry in it reappears each month with the same amount, account and day (day 31 becomes the last day of the month), with no end, until you stop it. Months appear as you navigate with ← / →, up to 24 months ahead of today. Deleting, editing or renaming one asks "only this month or the upcoming ones?" (`o` = only this month, `u` = this and upcoming).
 
 ## IV. Your data and backups
 
 <table>
   <tr>
-    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/backup.svg" width="44" alt=""></td>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/backup.svg" width="44" alt=""></td>
     <td>
       <ul>
-        <li><b>Where it lives:</b> <code>%APPDATA%\money-cli</code> on Windows and <code>~/.local/share/money-cli</code> on Linux (or the folder in the <code>MONEY_CLI_DADOS</code> variable). <code>kotsu --dados FOLDER</code> opens another folder.</li>
+        <li><b>Where it lives:</b> <code>%APPDATA%\kotsu</code> on Windows and <code>~/.local/share/kotsu</code> on Linux (or the folder in the <code>KOTSU_DATA</code> variable). <code>kotsu --data FOLDER</code> opens another folder.</li>
+        <li><b>A synced folder (two computers):</b> <code>kotsu --data-folder "G:\My Drive\Kotsu"</code> makes that folder this computer's data folder (it copies the database there the first time). Backups then go to the local folder, outside the sync. While Kotsu is open, a <code>kotsu.lock</code> file tells the other computer it is in use; <code>kotsu --force</code> opens anyway. <code>kotsu --default-data-folder</code> goes back to the local folder.</li>
         <li><b>Manual backup:</b> the <code>b</code> key creates <code>backups/money.YYYY-MM-DD-HHMMSS.sqlite</code> and keeps the 5 most recent copies. Kotsu never backs up on its own.</li>
-        <li><b>Using two computers (Google Drive):</b> on both, run <code>kotsu --pasta-dados "G:\My Drive\Kotsu"</code> (any existing data on the computer is copied there; if both already have data, choose which one wins). Keep the folder "Available offline". Use one computer at a time: Kotsu warns if it is open on the other one and refuses to open if Drive created conflicting copies (<code>--forcar</code> skips the warning). Backups from the <code>b</code> key stay in the local folder, outside Drive. <code>kotsu --pasta-dados-padrao</code> undoes it.</li>
-        <li><b>Merging with another device:</b> <code>kotsu --exportar data.json</code> writes everything to a file; on the other device, <code>kotsu --importar data.json</code> merges it with what is there (the most recent change to each entry wins, and deleted entries stay deleted). Do it both ways and check: <code>kotsu --conferir</code> shows a short code that is the same on both when the data is the same; <code>kotsu --conferir data.json</code> lists the differences. Before importing, Kotsu saves <code>backups/money.antes-da-troca.sqlite</code>.</li>
+        <li><b>Merging with another device:</b> <code>kotsu --export data.json</code> writes everything to a file; on the other device, <code>kotsu --import data.json</code> merges it with what is there (the most recent change to each entry wins, and deleted entries stay deleted). Do it both ways and check: <code>kotsu --verify</code> shows a short code that is the same on both when the data is the same; <code>kotsu --verify data.json</code> lists the differences. Before importing, Kotsu saves <code>backups/money.before-import.sqlite</code>.</li>
         <li><b>No password or encryption:</b> protect your computer and the folder as you would any personal file.</li>
         <li><b>Restore:</b> close the app, move the current <code>money.sqlite</code> elsewhere, copy the chosen backup to <code>money.sqlite</code>, open the app and check the totals.</li>
       </ul>
@@ -196,11 +192,21 @@ When you create a category, Kotsu asks whether it repeats every month (or press
   </tr>
 </table>
 
-## V. Under the hood
+## V. Updating from a Portuguese version
+
+Versions before November 2026 had Portuguese names. Updating keeps everything working:
+
+- The database is migrated on first open (schema 4: English table and column names). A copy is kept first as `money.before-v4.sqlite` next to the database.
+- `tema.toml` becomes `theme.toml`, the local folder `money-cli` becomes `kotsu`, and the old `MONEY_CLI_DADOS` variable still works.
+- The old flags (`--dados`, `--pasta-dados`, `--forcar`, `--exportar`, `--importar`, `--conferir`) still work, hidden from `--help`.
+- Exchange files from older versions import normally. Update **both** devices before comparing check codes: the code changed with the English names, so an old and a new version never show the same code.
+- The lock file is now `kotsu.lock`; a `kotsu.trava` from a computer not updated yet is still respected.
+
+## VI. Under the hood
 
 <table>
   <tr>
-    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/estrutura.svg" width="44" alt=""></td>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/structure.svg" width="44" alt=""></td>
     <td>Three layers, and a test fails if one of them imports what it must not. Financial rules (totals, installments, the quick-line parser) live in the domain; the screen only displays.</td>
   </tr>
 </table>
@@ -208,23 +214,23 @@ When you create a category, Kotsu asks whether it repeats every month (or press
 ```mermaid
 %%{init: {"theme": "base", "themeVariables": {"primaryColor": "#41274f", "primaryTextColor": "#ffe9f4", "primaryBorderColor": "#ff7fb8", "lineColor": "#ffa28c", "secondaryColor": "#291b33", "tertiaryColor": "#1d1424", "fontFamily": "Segoe UI, sans-serif"}}}%%
 flowchart LR
-    T["tela/<br>Textual: display only"] --> A["armazenamento/<br>SQLite, migrations, backup"]
-    T --> D["dominio/<br>money in cents,<br>installments, quick line"]
+    T["ui/<br>Textual: display only"] --> A["storage/<br>SQLite, migrations, backup"]
+    T --> D["domain/<br>money in cents,<br>installments, quick line"]
     A --> D
     A --> F[("money.sqlite<br>on your computer")]
 ```
 
-- Money is an integer number of cents, never a `float`; the sign comes from the type (income or expense).
+- Money is an integer number of cents, never a `float`; the sign comes from the kind (income or expense).
 - Every write is a transaction: all or nothing. Changed the schema? A numbered migration, with a copy of the database made first.
 - Totals are never stored: SQL computes them per month.
 
-Full contributor rules (in Portuguese): [AGENTS.md](AGENTS.md).
+Full contributor rules: [AGENTS.md](AGENTS.md).
 
-## VI. Development
+## VII. Development
 
 <table>
   <tr>
-    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/dev.svg" width="44" alt=""></td>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/dev.svg" width="44" alt=""></td>
     <td>Requires Python 3.11+. The tests never touch the network.</td>
   </tr>
 </table>
@@ -235,18 +241,18 @@ cd kotsu
 python -m venv .venv
 # Windows: .venv\Scripts\activate    Linux: source .venv/bin/activate
 pip install -e ".[dev]"
-kotsu --dados ./tmp                          # uses a test folder
-python ferramentas/verificar.py --rapido     # lint + fast tests
-python ferramentas/verificar.py              # everything, same as CI
+kotsu --data ./tmp                 # uses a test folder
+python tools/check.py --quick      # lint + fast tests
+python tools/check.py              # everything, same as CI
 ```
 
-## VII. License
+## VIII. License
 
 <table>
   <tr>
-    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/icones/licenca.svg" width="44" alt=""></td>
+    <td width="72" align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/icons/license.svg" width="44" alt=""></td>
     <td><a href="https://github.com/Sera-DAI/kotsu/blob/main/LICENSE">MIT</a>. Made with care, little by little.</td>
   </tr>
 </table>
 
-<p align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/imagens/divisor.svg" width="420" alt=""></p>
+<p align="center"><img src="https://raw.githubusercontent.com/Sera-DAI/kotsu/main/docs/images/divider.svg" width="420" alt=""></p>