memhouse 0.18.12 → 0.20.1

package/docs/guides/troubleshooting.md

@@ -35,9 +35,12 @@ as a failure.
   member's. This happens after a `passwd` on another machine, or a reset by the admin. Put
   the current password into `MEMHOUSE_PASSWORD` in `~/.memhouse/env` (or run
   `memhouse setup`, which asks), then restart the shipper.
-- **A pass that keeps withholding a session:** an adapter returned nothing for a session
-  the house already holds. The shipper refuses to replace a transcript with an empty one,
-  and says so on every pass, until the store is readable again.
+- **A pass that keeps withholding a session (0.18 rooms):** an adapter returned nothing for a
+  session the house already holds. The shipper refuses to replace a transcript with an empty
+  one, and says so on every pass, until the store is readable again.
+- **`vanish refused` (schema 3):** a store's list left sessions out, and memhouse would not
+  record them as gone without the editor's word. See
+  [Reading `memhouse doctor` on schema 3](#reading-memhouse-doctor-on-schema-3).
 - **Nothing to ship:** sessions are only shipped once the editor has written them.
 
 ## Daemons don't survive a reboot
@@ -47,15 +50,23 @@ as a failure.
 user services stop at logout. A rootless podman house from `deploy --local` has the same
 exposure, and `deploy` prints the fix.
 
+## The dashboard says to open it with `memhouse dashboard`
+
+The page has no token for this tab: it was opened by typing its address, in a new tab, after the
+browser restarted, or the token was replaced. Run `memhouse dashboard`. If the dashboard runs
+under another `MEMHOUSE_HOME`, run it with that home set. If it says "port N is not your
+dashboard", something else answers on that port: restart yours (`memhouse stop && memhouse
+start`), which moves it to a free port.
+
 ## The dashboard is empty, or stale
 
 - **It reads the house, not the machine.** Check `memhouse status` for the connection
   first.
-- **It reads precomputed stats,** refreshed at the end of each pass that shipped
-  something. On a house where nothing has shipped for a day, the stats age out, and a
-  running dashboard keeps reading them. Restart it (`memhouse stop && memhouse start`). It
-  then reads the rooms directly, until the next pass that ships refreshes the stats.
-  A fix is planned.
+- **On schema 3 it reads the `sessions` rows directly,** so it is as current as the last pass.
+- **On the 0.18 rooms it reads precomputed stats,** refreshed at the end of each pass that
+  shipped something. On a house where nothing has shipped for a day, the stats age out, and a
+  running dashboard keeps reading them. Restart it (`memhouse stop && memhouse start`). It then
+  reads the rooms directly, until the next pass that ships refreshes the stats.
 - **After an upgrade it shows the old version:** restart it (`memhouse update` does this).
 
 ## `EACCES` during `npm install -g`
@@ -65,14 +76,110 @@ owned by root.
 
 ## `refused`, `ACCESS_DENIED`, `Not enough privileges`
 
-- For a member, these are expected outside `mem.<you>_*` and the rooms shared with you.
-  `memhouse whoami` shows what your credential may do.
+- For a member, these are expected outside `mem.<you>_*`, your two capture tables in
+  `mem_archive`, and the tables shared with you. `memhouse whoami` shows what your credential
+  may do.
 - For `invite`, `members` or `convert`: you need the admin credential. See
   [Admin password](admin-password.md).
-- A room that should be yours but is refused usually means the house is older than this
-  version. Run `memhouse doctor`, then `memhouse migrate` if it says so.
+- A table that should be yours but is refused usually means the house is older than this
+  version. Run `memhouse doctor`, and do what it says: on the 0.18 rooms, `memhouse migrate`;
+  on schema 3, a missing capture table is created by an admin (the doctor line names the
+  command).
+
+## A schema-3 refusal (0.20)
+
+Each of these stops before changing anything:
+
+| Message | What it means | Do |
+|---|---|---|
+| `this house moved to schema 3 … memhouse migrate --v3-switch` | the admin converted your member; this machine still ships the 0.18 rooms | `memhouse migrate --v3-switch`, then `memhouse stop && memhouse start` |
+| `this house requires writers at schema 3+` | a 0.18 memhouse on a converted house | `memhouse update` to 0.20, then `--v3-switch` |
+| `'<m>' is being converted to schema 3` | the admin ran `--v3-prepare` but not yet `--v3-convert` | wait for the conversion, then install |
+| `the house holds '<m>' on schema N; --schema M contradicts it` | an explicit `--schema` disagrees with the member's tables | leave `--schema` out; the install follows the house |
+| `this house holds members on the 0.18 rooms and members on schema 3` | a house mid-conversion, and a new member | state which one this install joins: `--schema 2` or `--schema 3` |
+
+The whole procedure is in [Upgrade to 0.20](upgrade-to-0.20.md).
+
+`status`, `doctor` and `stats` name the same situations when the house answers but your
+tables are not where this install looks. They say so instead of "not connected"; `status
+--json` then has `"reachable": true`, `"connected": false` and a `rooms_problem`:
+
+| `rooms_problem` | Message | Do |
+|---|---|---|
+| `moved` | `this house was moved to schema 3, and this machine still reads and ships the 0.18 rooms` | `memhouse migrate --v3-switch`, then `memhouse stop && memhouse start` |
+| `not-moved` | `this machine reads schema 3, but '<m>' … is still on the 0.18 rooms` | the admin converts the house first; until then `MEMHOUSE_SCHEMA=2` in `~/.memhouse/env` |
+| `admin` | `'<user>' administers this server and owns no rooms` | this install is configured with an administrator credential; make a member: `memhouse install --admin-user <user> --member <you>` |
+| `none` | `no tables for '<m>' in '<house>'` | `memhouse install` builds them; or the house name in `~/.memhouse/env` is wrong |
+
+## Reading `memhouse doctor` on schema 3
+
+On a schema-3 member, `doctor` adds these lines about the house. A failing line carries a hint
+after it.
+
+| Line | What it means | Do |
+|---|---|---|
+| `conversation tables: 6/6 …, keys correct` / `capture tables: 2/2 …` | your six tables in the house's database and your two in its archive exist, with the right sorting keys | a missing table: an admin creates it, with the command the hint names; a wrong key: the table has to be rebuilt from the template by its owner |
+| `columns: every schema-3 table matches the template` | names, types and kinds match the version you run | a missing column, or one of the three columns retyped in harness-sessions-sql v1: `memhouse ship --ensure-schema` for your conversation tables. A member cannot alter its two archive tables: ask the house's admin, who can (for the three retyped columns, the statements are in the 0.20 release notes' Known issues). Any other changed type, or a lost `MATERIALIZED` clause: the table has to be rebuilt by its owner |
+| `member name: no other member's tables within reach` / `member names collide: …` | whether your grant's prefix reaches another member's tables | see [Two member names that collide](#two-member-names-that-collide) |
+| `N imported session(s) need a re-import` | the member is on the 0.20 development builds' layout (`<m>_turns`) and holds conversations `memhouse import` wrote there | keep the export, and import it again after the move: [Upgrade to 0.20](upgrade-to-0.20.md#imported-sessions-on-a-development-build) |
+| `identity stamping: … all attributed` | every row carries the user that wrote it (`writer`) | an empty writer means a writer used `async_insert=1`; see [Operate a house](operate.md#server-settings-that-matter) |
+| `ts stable: …` | no message part or call changed its time between versions | a moved time is an editor reader breaking a rule; report it with the sample the line shows |
+| `dedupe: …` | captured sessions have absorbed the rows converted from 0.18 | it clears after a pass that captures the session to the end (`memhouse ship`) |
+| `pricing: …` / `token capture: …` | every model has a price; every editor reports tokens | `memhouse update` (prices ship with each release; `memhouse q spend` lists unpriced models); an editor that reports no tokens shows cost as $0, not unknown |
+| `removed content: …` | messages kept as removed versions (a revert, a rewind, a deleted message) | nothing; `memhouse q removed` lists them, and no total counts them |
+| `forks: …` | fork links, and how many are billed once (their copied usage counted only in the origin) | nothing; a fork that could not be verified is counted in both sessions |
+| `host identity …` | this machine's id, its sessions, and its 0.18 id if it had one | nothing |
+| `the last pass refused to record vanished sessions in N store(s): …` | the store's list left sessions out, and memhouse would not record them as gone without the editor's word | read `~/.memhouse/logs/shipper.log` (its `vanish refused` lines). For a store whose list is empty, the line names a command: if its sessions really were deleted, run it, `memhouse doctor --confirm-empty-store <editor>:<store>` ([Daemons](daemons.md)) |
+
+## Two member names that collide
+
+A member is granted its tables by one prefix: `bob` holds `mem.bob_*`. If another member's name
+is `bob` plus an underscore and more (`bob_smith`), that prefix also matches `bob_smith`'s
+tables, so `bob` can read and write them. ClickHouse 26.7 behaves this way (checked
+2026-10-22). Mostly the longer name's tables are exposed, to the shorter name. When the longer
+name's extra part starts one of the shorter name's table names, the reverse holds too:
+`bob_session` holds `mem.bob_session_*`, which matches `bob`'s `bob_session_parts`.
+
+- **0.20 refuses to create such a member**, by install or invite: `'bob_smith' collides with
+  'bob'`. Pick a name that neither starts with another member's name and an underscore, nor is
+  the start of one. The check finds the other member by its tables, so a member that has none
+  yet (provisioned by hand, never shipped) is not caught: check the users as below too.
+- **`memhouse doctor`**, run as the shorter-named member, shows `member names collide: …`.
+- **`memhouse migrate --v3-shares` refuses** to move shares in such a house, whichever of the
+  two members it is run for. It also finds the other member by its tables only.
+- **`memhouse share --revoke` leaves a reader's 0.18 wildcard grant for the admin when it
+  matches another member's tables:** run by `bob`, a REVOKE on `mem.bob_*` would also strip the
+  reader's grants on `bob_smith`'s tables. Run by `bob_smith`, the revoke takes its own wildcard
+  back as usual, since `mem.bob_smith_*` matches none of `bob`'s tables (it would be left for
+  `bob_session`). A colliding name counts whether it is found by its tables or by its user, since
+  a member with no tables, or whose tables the revoking member cannot see, still holds its grants.
+  A user counts only when it holds a member's grant in this house or its archive (ALL, INSERT,
+  CREATE, DROP, ALTER, OPTIMIZE or TRUNCATE, or the right to grant, on its own tables or on a
+  broader target that covers them, such as an admin's `*.*`), holds a role, or its grants cannot
+  be read. A reader that holds no role, and the same person's account in another house on the
+  server, do not.
+  The wildcard is left too when it matches a table memhouse did not make for the member, or when
+  the house's tables or users cannot be listed. Two names can even share a table: `bob`'s 0.18
+  room `bob_tool_calls` is also `bob_tool`'s schema-3 `calls` table.
+- **The admin takes a left wildcard back by hand**, because `--v3-shares` refuses here. A REVOKE
+  on it takes the reader's grants on every table it matches, so first note what the other
+  member had shared with that reader. `SHOW GRANTS` lists those grants merged into the wildcard,
+  so read the other member's record (`SELECT substring(key, 7) AS reader, argMax(value,
+  updated_at) AS state FROM mem.bob_smith_meta WHERE key LIKE 'share:%' GROUP BY key`), and grant
+  them again after the REVOKE, in the form that member's layout uses: its exact schema-3 tables,
+  or its 0.18 wildcard. If the reader is the other member itself (`bob` shared with
+  `bob_smith` in 0.18), a REVOKE on `mem.bob_*` from `bob_smith` also takes its SELECT on its own
+  tables: revoke only `bob`'s own tables from it instead.
+- **An admin can list every member** to check a house: `SELECT name FROM system.users ORDER BY
+  name`, then look for one name that is another's plus `_`.
+
+memhouse has no command yet that untangles an existing pair. Until it does, an admin decides
+whether to stop one of the two members shipping, or to replace the shorter name's wildcard
+grant with grants on its exact tables, by hand. Ask before changing either: it touches
+another person's data.
 
 ## Still stuck
 
-Run `memhouse doctor` and `memhouse status --json`, and open an issue with both outputs.
-Check them before posting, and remove anything private, such as a host name.
+Run `memhouse doctor` and `memhouse status --json`, and send both outputs to
+security@memhouse.io (the only public contact for now). Check them before sending, and remove
+anything private, such as a host name.

package/docs/guides/uninstall.md

@@ -12,11 +12,12 @@ npm uninstall -g memhouse            # then remove the package
 - **The default is the conservative one.** Stopping the shipper is routine: before an
   upgrade, while debugging, or when a laptop should go quiet for a week. It should not
   also mean "forget which house I use and who this machine is".
+- **The dashboard's token goes with every tier.** The next `memhouse start` makes a new one.
 - **`--full-removal` asks first.** It deletes `host.json`. A later reinstall derives the
   same identity again from the machine's own id, so your history stays one machine, unless
   the machine was renamed in between or has no readable machine id. Then it comes back as
   a new host.
-- **Your memory stays.** The rooms in ClickHouse are untouched by every tier. What the
+- **Your memory stays.** Your tables in ClickHouse are untouched by every tier. What the
   shipper wrote can be rebuilt from the local session stores with `memhouse ship --full`,
   for as long as the editors keep them.
 
@@ -24,8 +25,8 @@ npm uninstall -g memhouse            # then remove the package
 
 - **A local house** from `deploy --local`: `memhouse deploy --down` removes the container
   **and its data volume**. That deletes the memory, and there is no undo.
-- **A shared server:** an administrator drops your rooms and user. See
-  [Operate a house](operate.md).
+- **A shared server:** an administrator drops your user and your tables, in the house's database
+  and its capture archive. See [Operate a house](operate.md#removing-a-member).
 
 ## Removing the skills
 

package/docs/guides/update.md

@@ -14,6 +14,12 @@ memhouse update --check    # compare versions, change nothing
 3. **It stays on your channel** (`MEMHOUSE_CHANNEL`). See
    [Configuration](configuration.md#channels).
 
+It asks the registry npm installs from: `npm config get registry`, or `npm_config_registry`
+in the environment. Behind a mirror, that is the mirror; `update --check` prints which
+registry it read and, when it could not, why (an HTTP status, a refused connection, no
+answer). A registry that needs a login is read without one, so `update` cannot see its tags;
+install by hand there (`npm install -g memhouse@<version>`, then `memhouse update --no-install`).
+
 Upgraded by hand already? Finish the job without reinstalling:
 
 ```bash
@@ -26,6 +32,16 @@ version it booted with, and hands over when they differ: under systemd or launch
 exits so the supervisor restarts it; with nothing supervising, it re-executes itself.
 `update` just makes the switch immediate.
 
+The `/mem` skills follow on their own too. The first `memhouse` command after an upgrade, or
+the shipper's restart, replaces every skill copy bound to this install with the new version's
+(see [Search, resume and skills](search-and-resume.md#skills-for-your-agents)). Reload them in
+a running Claude Code with `/reload-plugins`. Copies bound to another memhouse install on the
+same machine are left to it, and a copy is never replaced by an older one.
+
+**Coming from 0.18?** Updating to 0.20 keeps the house on the 0.18 rooms. The move to
+schema 3 is a separate admin step, then one switch per machine:
+[Upgrade to 0.20](upgrade-to-0.20.md).
+
 ## Several machines on one house
 
 Every machine of every member runs its own shipper. Upgrade them all.

package/docs/guides/upgrade-to-0.20.md

@@ -0,0 +1,188 @@
+# Upgrade a house from 0.18 to 0.20
+
+0.20 stores sessions in a new layout, schema 3: the harness-sessions-sql profile (`session_parts`, `session_usage`, `calls`, `sessions`, `session_links`, `session_lifecycle`, and the raw archive beside them). Each session is keyed by its harness store, tool output is kept in full, removed content is kept as removed versions, and a fork's copied prefix is billed once. A 0.18 house is in the old layout (the "rooms"), and moving it is a deliberate, one-time step. **`memhouse update` does not do it.**
+
+It happens in three parts:
+
+| Who | What | Command |
+|---|---|---|
+| every machine | install 0.20; it keeps shipping into the 0.18 rooms | `memhouse update` |
+| the house's admin, once per member | fence the 0.18 writers off, rename the rooms, convert, check, move the shares | `memhouse migrate --v3-prepare`, `--v3-convert`, `--v3-reconcile`, `--v3-shares` |
+| every machine, after the conversion | capture into schema 3 from now on | `memhouse migrate --v3-switch` |
+
+Rehearse the move end to end on a disposable ClickHouse first, before you run it on a house that matters.
+
+## 1. Every machine: install 0.20
+
+```bash
+memhouse update
+```
+
+Behind a registry mirror, 0.18's `update` cannot see the new version: it asks
+registry.npmjs.org, whatever npm is configured with (0.20's `update` reads npm's registry).
+Install from the mirror with npm, then let memhouse finish the job:
+
+```bash
+npm install -g memhouse@<version>
+memhouse update --no-install
+```
+
+The house is not converted. 0.20 keeps shipping the 0.18 rooms until the member is converted and the machine is switched; as every update does, it may create a missing room or column, or run a pending 0.18 migration (after asking). A machine can be upgraded days before the conversion.
+
+## 2. The admin: convert the member
+
+**Back up first.** Before the first `--v3-prepare`, take a backup of the house and its accounts,
+and check it ([Backups](operate.md#backups) has both statements). A 0.18 house has no
+`<db>_archive` yet, so back up `<db>` and the accounts. The steps below keep the 0.18 rows
+(renamed, never deleted), but a backup is the only way back from a mistake made by hand.
+
+**Check the house for colliding member names.** `--v3-shares` refuses to move the shares of a
+member whose name is another's plus an underscore, or the start of one (`bob`, `bob_smith`),
+because each member's grant there reaches the other's tables. Check before you start:
+[Two member names that collide](troubleshooting.md#two-member-names-that-collide).
+
+These are admin steps, run with an administrator credential lent for the command only (never stored; see [the admin password guide](admin-password.md)). They take the administrator as `invite` and `members` do: `MEMHOUSE_ADMIN_USER` and `MEMHOUSE_ADMIN_PASSWORD` (or `--admin-user` and `--admin-password-file`). The house's address is `MEMHOUSE_URL`, or this machine's own env file when it has one; with no admin credential, or no address, a step refuses before it connects and names what is missing. `--member` names whose house is converted. `--v3-prepare` and `--v3-convert` take `--dry-run`, and refuse before changing anything when the house is not in the state they expect; `--v3-reconcile` only reads. The steps that change something ask first; `--yes` answers for a script, or an agent with no terminal (do not pipe `yes` into them).
+
+```bash
+export MEMHOUSE_URL=<house-url>            # unless this machine's own install points at the house
+export MEMHOUSE_ADMIN_USER=<admin>
+read -rs MEMHOUSE_ADMIN_PASSWORD && export MEMHOUSE_ADMIN_PASSWORD
+
+memhouse migrate --v3-prepare   --member <m> --dry-run   # what it would do
+memhouse migrate --v3-prepare   --member <m>             # fence + rename
+memhouse migrate --v3-convert   --member <m> --dry-run   # what it would convert
+memhouse migrate --v3-convert   --member <m>             # the rooms into the profile tables
+memhouse migrate --v3-reconcile --member <m>             # every converted row and bucket checked
+memhouse migrate --v3-shares    --member <m> --dry-run   # the grants it would make
+memhouse migrate --v3-shares    --member <m>             # the member's shares, onto schema 3
+
+unset MEMHOUSE_ADMIN_PASSWORD
+```
+
+`MEMHOUSE_USER` and `MEMHOUSE_PASSWORD`, which earlier drafts of this guide used for the admin, still
+work for these steps in 0.20 when no admin variable is set, with a note that they are deprecated
+there. They are the member's names; the admin steps stop reading them in the next minor release.
+A credential the server refuses is named as one: `could not authenticate as '<admin>' at <url>`.
+
+What each step does:
+
+- **`--v3-prepare`** does two things:
+  - It writes `min_writer_schema = 3` into the member's `meta` room. Every 0.18 writer now refuses to ship ("this house requires writers at schema 3+"). A 0.20 machine that has not switched yet refuses too, and says how to switch.
+  - It renames the member's three 0.18 rooms (`<m>_messages`, `<m>_tool_calls`, `<m>_sessions`) into `<db>_archive` as `*_pre_v3`, in one statement. **Nothing is deleted**: the rooms are kept whole, and the conversion reads them from there.
+
+  Run a second time, it says the member is prepared already and changes nothing. It refuses a half-done state, for example one room renamed and another not.
+- **`--v3-convert`** creates the schema-3 tables and the archive, grants the member its capture tables, and converts the 0.18 rows into `session_parts`, `session_usage`, `calls` and `sessions` (`adapter = 'legacy'`). Tokens are carried as 0.18 stored them, with flags that say how to read them: Gemini CLI's input includes its cached tokens, and the totals take them out. 0.18 never stored Gemini's thought tokens, and they cannot be recovered.
+  - Every row keeps its `host` as 0.18 wrote it (see [Host identity](#host-identity)).
+  - A session 0.18 holds more than once (under a prefixed and a bare id, from two users, or from one machine under several host ids) becomes one session, at the host of its newest row and the path of its transcript. The newest copy converts as it is. Rows of an older copy that the newest one holds again are not converted (duplicates). Rows only an older copy holds are content that left the session, and convert as removed versions: kept and searchable (`memhouse q removed`), never counted.
+  - Rows of one id under two hosts are one session when the id cannot be another session's: a UUID-like id of Claude Code, Codex, Gemini CLI, Cursor, Cursor agent, VS Code, Copilot CLI or OpenCode, or hosts a reported host pair names as one machine. Other editors' ids (Goose, Zed and the rest) can repeat across machines, so their rows under two hosts are one session only when they read as one machine whose 0.18 id changed: one 0.18 stream (one id, one user, imported or shipped but not both), each host holding its own run of positions, each run shipped after the one before it, and no reported host pairs naming the hosts as two machines. Two machines that used one id both started at the first position and wrote over each other's rows, so their runs interleave, or the lower run was shipped later. Those stay one session per host, as do rows in two streams (an import beside a shipped copy, two users) and two 0.18 ids (copies) on two hosts.
+  - A 0.18 session with no message rows, only its sessions row (a title and a path), converts as a session without messages: its title, folder and path, with its 0.18 times as its start and end and no totals. It is grouped by host as other sessions are. The session list finds it by its name or folder; a text search, which reads messages, does not.
+  - It is resumable: re-run it after an interruption, and finished buckets are skipped.
+  - Only a conversion that ran to the end opens the house: it writes a `profile_converted` mark into the member's `meta`, and installs and `--v3-switch` wait for it.
+  - Each converted session gets its store, `harness_path`, from the path 0.18 recorded. For
+    OpenCode the store is the database file: a row whose path names a channel DB
+    (`opencode-<channel>.db`) keeps that file; every other OpenCode row is keyed by the default
+    `<data folder>/opencode.db`, the only database 0.18 read.
+- **`--v3-shares`** moves the member's shares. A 0.18 share is a grant on the old rooms, and
+  the rooms were renamed, so without this step a scoped reader loses access.
+  - It re-creates only the shares memhouse recorded in the member's `meta`.
+  - It prints every grant and row policy before applying it.
+  - It refuses, changing nothing, when the record and the grants ClickHouse holds disagree: a
+    grant made by hand, or a recorded share with no grant behind it. It lists each one.
+  - The new share is SELECT on exactly the six profile tables (`session_parts`, `session_usage`,
+    `session_links`, `session_lifecycle`, `calls`, `sessions`), never the archive. A 0.18 full
+    share's wildcard (`<m>_*`, which also reached `meta`, `events` and the stat tables) is taken
+    back.
+  - A scope keeps its meaning: `source=` becomes `harness=`; `since`/`until` filter parts, usage,
+    calls and lifecycle by their own time (a row with no time is outside a time scope), and
+    sessions by their start; a project or folder scope covers parts, calls and sessions (the
+    sessions row carries the totals).
+- **`--v3-reconcile`** recomputes every converted row's content sha from its columns and checks that every bucket holds every key the 0.18 rows make. Exit 0 means every row and bucket checks out.
+
+Once every member is converted, take a backup again, now of both databases, `<db>` and
+`<db>_archive`, with the accounts ([Backups](operate.md#backups)).
+
+## 3. Every machine: switch
+
+**Which machines.** Every machine that ships as the member switches, and the house does not
+reach them: the member does it on each one. To know which machines those are, the admin reads
+the member's last ship per machine from its `meta` room (still in `<db>` after the conversion):
+
+```sql
+SELECT substring(key, 11) AS writer, value AS last_ship
+FROM <db>.<m>_meta FINAL
+WHERE startsWith(key, 'last_ship:')
+ORDER BY last_ship DESC
+```
+
+`writer` is `<member>@<machine>`, the 0.18 name of each machine that shipped. A 0.20 machine
+that has not switched refuses to ship, and its `memhouse status` names the switch; a 0.18 machine
+refuses until it is updated to 0.20.
+
+```bash
+memhouse migrate --v3-switch --dry-run
+memhouse migrate --v3-switch
+memhouse stop && memhouse start
+```
+
+`--v3-switch` sets `MEMHOUSE_SCHEMA=3` in this install's env file and changes nothing else. It refuses unless the house holds the member's schema-3 tables and, for a member fenced off its 0.18 rooms, the conversion ran to the end (its `profile_converted` mark): a machine never captures into a half-converted house.
+
+After the restart, the shipper captures this machine's transcripts into schema 3. On its first pass it dedupes: each captured session absorbs the converted rows of the same session, so nothing is counted twice. Rows the transcript no longer has are kept and counted once.
+
+Then check the result:
+
+```bash
+memhouse doctor          # every house check green
+memhouse q recent        # the sessions, once each
+```
+
+## Sessions deleted before the move
+
+A session whose transcript was deleted from disk before the move keeps its converted rows, and
+nothing in the house says the file is gone: 0.18 recorded no deletions, and the conversion
+reads only the rows. On schema 3 a deletion is recorded when a capture sees it, which needs the
+file to have been there at an earlier capture. Such a session therefore reads as current, under
+the machine's 0.18 id.
+
+## Imported sessions on a development build
+
+A member that ran a 0.20 development build has `<member>_turns`, the layout the profile replaces. If you used `memhouse import claude-ai` there, those conversations live only in `<member>_turns`. A recapture reads the editors' files, and an import has none, so moving the member does not bring them back.
+
+- **Before the move.** `memhouse doctor` names them as "N imported session(s) need a re-import". `memhouse install`, `migrate --v3-prepare` and `migrate --v3-convert` refuse the member with the same count while this build cannot import into the profile tables. A `--dry-run` only says so.
+- **Keep the export.** Keep the export you imported from: the zips, or the archive folder.
+- **After the move, import it again,** with a build that writes imports into the profile tables. Run it as a dry run first:
+
+```bash
+memhouse import claude-ai <the export> --update             # dry run: every conversation reads as new
+memhouse import claude-ai <the export> --update --write
+```
+
+  The keys are the same as before, so the re-import stores the same sessions under the same ids.
+
+## Host identity
+
+0.20 names a machine by `sessions-model/host/v0`: a fingerprint derived from the OS machine id, the same value for every reader on the machine. 0.18 used its own id (`<name>-<8 hex>`).
+
+Converted rows keep the 0.18 id. On this machine it is an alias of the new one, so dedupe matches a converted session to its capture. Rows a machine shipped and whose transcripts are gone stay under its 0.18 id: they are history and are still counted.
+
+The two ids cannot be computed from each other, so the conversion cannot join them; the machine can. When it switches, and on each capture pass, it records its 0.18 id as its own in the member's `meta` (`host_alias:<0.18 id>`), and `memhouse status`, `q machines`, `q hosts`, `q coverage`, `--host` and `memhouse doctor` read that id's rows as the machine: one writer, not two. No row is rewritten. A member's aliases come from its own `meta` and apply to its own rows only; a housemate reading a share sees the hosts as stored.
+
+## Rolling back
+
+- **Before any machine has switched,** rename the rooms back, and lift the fence with a newer `meta` row (`meta` is latest-wins):
+
+  ```sql
+  RENAME TABLE <db>_archive.<m>_messages_pre_v3 TO <db>.<m>_messages,
+               <db>_archive.<m>_tool_calls_pre_v3 TO <db>.<m>_tool_calls,
+               <db>_archive.<m>_sessions_pre_v3 TO <db>.<m>_sessions;
+  INSERT INTO <db>.<m>_meta (key, value) VALUES ('min_writer_schema', '0');
+  ```
+
+  The converted tables stay; an admin may drop them.
+- **After a machine has switched,** its captures since then exist only in schema 3. Rolling back means losing them from the 0.18 view, so do not, unless you are prepared to re-ship those sessions from their transcripts with 0.18.
+
+## What changes for readers
+
+- `memhouse q …` reads schema 3: `q recent`, `q session <ref>`, `q search`, `q spend`, and the rest (`memhouse q --list`).
+  - A session's ref names its store (`<harness>:<id>~…`); a bare id still resolves when it is unique.
+- `memhouse q removed` lists what is kept as removed versions: a revert, a rewind, a message deleted at the source. No other read shows them.
+- The dashboard and the `/mem` skills read schema 3 once the install is switched.

package/docs/releases/README.md

@@ -5,7 +5,8 @@ do, how to upgrade, what is deprecated and when it goes, and what was deferred.
 
 | version | date | headline |
 |---|---|---|
-| [0.18.12](v0.18.12.md) | 2026-10-29 | skills: allowed tools restricted to read-only commands |
+| [0.20.1](v0.20.1.md) | 2026-11-02 | invites expire; `memhouse plugins install codex`; per-command help and clearer CLI answers |
+| [0.20.0](v0.20.0.md) | 2026-10-29 | schema 3: a session is its store, nothing cut or lost, forks billed once, ten editors through normalisers; Apache-2.0 |
 | [0.18.11](v0.18.11.md) | 2026-10-10 | sessions with subagents stop re-shipping; security: no stored credential sent to `invite --url` |
 | [0.18.10](v0.18.10.md) | 2026-10-08 | security: the admin password never on argv; no member password printed; a scoped share reaches only its scope |
 

package/docs/releases/v0.18.10.md

@@ -82,7 +82,7 @@ memhouse ships into the house, where the archive is insert-only. (#20)
 - **Tests guard it.**
   - A unit test fails on any print call that evaluates a password: as an argument,
     concatenated, or interpolated.
-  - `misc/invite-matrix.sh` runs every install, invite and passwd path against a real
+  - `misc/invite-matrix.sh` (repository) runs every install, invite and passwd path against a real
     ClickHouse and checks each output against the real passwords.
 
 ### A scoped share shares only what its scope filters (#13)
@@ -163,8 +163,8 @@ These do not change the installed package:
 - **memhouse.io describes 0.18** (#12): one layout, five skills, the honest editor count
   (16 adapters reading 18 apps).
 - `memhouse.io/.wrangler` (wrangler's local cache) is no longer tracked.
-- `misc/one-layout-matrix.sh` now asserts the scoped-share boundary, and
-  `misc/invite-matrix.sh` the admin-password sources: environment, stdin, `--keep-admin`,
+- `misc/one-layout-matrix.sh` (repository) now asserts the scoped-share boundary, and
+  `misc/invite-matrix.sh` (repository) the admin-password sources: environment, stdin, `--keep-admin`,
   and none. The file source is covered by unit tests. CI runs both matrices against
   ClickHouse 25.11 and 26.7.
 
@@ -172,7 +172,7 @@ These do not change the installed package:
 
 **The gentar kit v0.9.3 bump (#18) also moves to 0.18.11.** It changes CI only.
 
-**The subagent re-ship fix moves to 0.18.11.** It is on branch `claude/subagent-stable-seq`
+**The subagent re-ship fix moves to 0.18.11.** It shipped there
 and stops a Claude Code session with subagents from re-shipping whole on every pass, which
 is what grew one house to 16.2 M message rows for about 295 k real ones. It was reviewed
 before release by four models. Three said "ship with fixes"; the fourth said "do not ship",
@@ -221,6 +221,6 @@ every tag and what it changed.
 - No live house was touched to prepare this release.
 - **No drill was run for this release; waived by the maintainer (2026-10-08). The drill runs before 0.19.0.**
   `AGENTS.md` asks for a drill before a release that changes a surface a person touches,
-  and this one changes install, invite and share. A drill was prepared on the testbed, but
+  and this one changes install, invite and share. A drill was prepared on a test VM, but
   its setup could not run in the release environment, and the maintainer chose to release
   without it.

package/docs/releases/v0.18.11.md

@@ -58,7 +58,7 @@ Now:
 - **An admin given for this command** (`--admin-user`, or an exported
   `MEMHOUSE_ADMIN_USER`, with its password from a file, stdin, the environment or a prompt)
   still provisions at `--url`. That is what the person typing the command asked for.
-- **`misc/invite-matrix.sh` points `--url` at a spy server** and asserts that it receives
+- **`misc/invite-matrix.sh` (repository) points `--url` at a spy server** and asserts that it receives
   nothing but a ping. On 0.18.10 the spy received two authenticated requests.
 
 **Action:**
@@ -154,7 +154,7 @@ Earlier published packages carried those copies without the notices.
   only) instead of being dry-run on the CI host.
 - **The suite tears down only a house it created.** It refuses to deploy over an existing
   house, and a failed teardown fails it.
-- **`misc/skill-recipe.sh` runs the skills' queries verbatim, extracted from the docs.**
+- **`misc/skill-recipe.sh` (repository) runs the skills' queries verbatim, extracted from the docs.**
   The fixture includes a superseded parse and a subagent block.
 
 ## Pre-tag list (0.18.10 review): final status
@@ -184,4 +184,4 @@ Earlier published packages carried those copies without the notices.
   - invite 58/58;
   - one-layout 62/62.
 - **Second looks:** a second model reviewed #21 and #22.
-- **Labs:** kept light, because the lab host's RAID was degraded. No live house was touched.
+- **Labs:** kept light. No live house was touched.