Upgrading

There is no kotoba upgrade command. The subcommands are setup, doctor, serve and discord, and upgrading is your package manager's job.

From an install

pip install --upgrade "kotoba-companion[server,voice,cli,web,mcp]"
kotoba doctor

Keep the extras you had. Dropping one is not an error you will see immediately — it is a capability that quietly stops being offered, which is exactly what doctor lists:

From a clone

git pull
pip install -e "api/[server,voice,mcp,web,cli]"
npm install          # only if you are working on the frontend

A clone runs the dev server, so there is nothing to rebuild for the UI. If you want the packaged copy refreshed — the one an install without Node would get — that is python scripts/build_web.py, and it needs Node and refuses while any root dotenv file exists.

What an upgrade replaces

The installed package, entirely. That is the Python code, the packaged personality file, the skills, the terminal's artwork, and <package>/web — the compiled browser UI. A released wheel cannot carry a UI from a different version or a stale one: the build backend refuses to package a web directory that is absent, stale, or built for another version, and stamps it with a digest of its own contents. That guard runs for a wheel and an sdist; an editable install is exempt on purpose, because a contributor runs the dev server and has nothing packaged to check.

On a clone, the working tree. Including soul/default.md. If you edited her personality in place, git pull is where you find out.

What an upgrade does not touch

~/.kotoba, in full: your settings, the master key, the database (on a normal install), her memory, her files, her models, your plugins and your MCP config. That separation is the whole reason the database default moved out of the checkout — unpacking a new version into a new folder used to start empty, with nothing on screen saying why.

The database

Migrations run on connect, in every process, tracked by SQLite's user_version. Version 0.10.0 opens at schema v4. Each step is idempotent, because the step and the version bump are not atomic — a crash between them re-runs the step. An existing database with all its tables is adopted rather than recreated.

There is no downgrade path. Once a newer Kotoba has opened your database, an older one may or may not cope with it; nothing in the code makes that safe. Back the file up before a major upgrade, and remember that it is one file plus its -wal and -shm sidecars.

Two processes upgrading the same fresh database at once — the terminal beside the server — is handled: busy_timeout is set before anything else, the WAL conversion is retried, and the read views are rebuilt inside one immediate transaction so two racers cannot collide.

After upgrading

kotoba doctor runs the checks in the order that decides whether she can run: her personality file, the database (which it opens and migrates, then prints the path and schema version), the encryption library, every saved secret, the model key, the voice key, then the optional extras and the MCP servers. A missing optional piece never fails the run, and it says what each one costs you rather than only that it is missing.

The two things most worth reading in that output after an upgrade:

• the database row, because it names the file that was actually opened — and adds "Beside the package, not in your home" if you are on an old clone layout;
• the saved keys row, because it is where a master key that did not travel shows up as a list of names rather than as a voice that mysteriously went quiet.

Version numbers

Versions start at 1.0. A fix or a small addition moves the last number; a release that changes how Kotoba behaves for you moves the middle one, and the changelog says so in plain words before it says so in a number. The third number is not decoration — Python normalises 1.01 to 1.1, so a small fix written that way would publish as a whole minor release.