memhouse 0.18.8 → 0.18.10

package/docs/tutorials/01-first-house.md

@@ -0,0 +1,132 @@
+# Tutorial 1: your first house
+
+One machine, about ten minutes. At the end, every coding-agent session on this machine
+is in a ClickHouse you own. You can see them in a dashboard, search them, and ask an agent
+about them.
+
+**You need:**
+
+- Node 24 or newer;
+- docker or podman, for the local ClickHouse;
+- at least one editor that has written sessions: Claude Code, Codex, Cursor, Zed, and so on.
+
+## 1. Install
+
+```bash
+npm install -g memhouse
+```
+
+On a distro-packaged Node (Linux, global prefix under `/usr`) this needs `sudo`. On
+Homebrew, nvm, fnm or volta it must not have it. [The install guide](../guides/install.md#eacces-on-install)
+tells the two apart.
+
+## 2. See what is on this machine
+
+```bash
+memhouse discover
+```
+
+This is a read-only preflight. It lists every editor it found, how many sessions each one
+holds, the directories it watches, and any ClickHouse it can reach. Nothing is written
+anywhere.
+
+## 3. Stand up a house
+
+```bash
+memhouse deploy --local
+```
+
+This does four things:
+
+1. It starts ClickHouse in a container bound to `127.0.0.1:8123`, so only this machine
+   can reach it. The data lives in a named volume.
+2. It creates two users. `memhouse_root` administers the house. A **member** named after
+   your OS user (`polat`, say) ships your sessions, and holds one grant: `mem.polat_*`.
+   Your rooms are `mem.polat_sessions`, `mem.polat_messages`, `mem.polat_tool_calls`, and
+   so on.
+3. It writes both credentials to `~/.memhouse/env`, mode 600. A local house is the one
+   case where the admin credential is kept, so that `memhouse invite` works later with
+   no flags.
+4. It installs against the house and ships everything once.
+
+Already have a ClickHouse? Skip this step and use `memhouse onboard`, which asks for
+it. See [the install guide](../guides/install.md).
+
+## 4. Check it worked
+
+```bash
+memhouse status
+```
+
+Look for a connection check mark, row counts in your rooms, and a recent "last shipped"
+time. `memhouse doctor` goes further. It checks the whole pipeline and names anything
+skipped.
+
+## 5. Keep it shipping, and open the dashboard
+
+```bash
+memhouse start
+```
+
+This starts two background daemons. The shipper runs an incremental pass every five
+minutes. The dashboard runs at **http://localhost:4640**: sessions, cost by model and
+editor, tool calls, and which machine wrote what.
+
+Those daemons do not survive a reboot. To make them permanent:
+
+```bash
+memhouse service install      # systemd --user on Linux, a LaunchAgent on macOS
+```
+
+## 6. Find something
+
+```bash
+memhouse search "connection refused"
+```
+
+Each hit names the session, its project and its date. Reopen one:
+
+```bash
+memhouse resume claude-code:6b1f…
+#   cd /path/to/project && claude --resume 6b1f…
+```
+
+`resume` **prints** the command rather than running it. You see the directory and the id
+before anything opens.
+
+## 7. Let your agents remember
+
+```bash
+memhouse plugins install claude
+```
+
+This installs five skills into every Claude Code config directory it finds. You choose
+which ones; all are selected by default. In any Claude Code session afterwards:
+
+```
+/mem:recall how did I fix the ClickHouse auth error last month?
+```
+
+The agent searches your house, reads the sessions that match, answers from them, and
+cites the sessions it used. `/mem:house` reports the state of the house.
+
+## What you have now
+
+- `~/.memhouse/env` holds the connection and both credentials. Never paste it anywhere.
+- `~/.memhouse/host.json` holds this machine's identity. Every row it ships carries it.
+- A ClickHouse container with your memory in a named volume.
+
+## Undo it
+
+- `memhouse uninstall` stops everything and keeps the house.
+- `memhouse deploy --down` removes the container **and its volume**, which **deletes the
+  memory**.
+
+See [Uninstall](../guides/uninstall.md).
+
+## Next
+
+- [Tutorial 2](02-join-a-house.md): join a team's house instead of running your own.
+- [Configuration](../guides/configuration.md): ship only some editors or directories.
+- [How memory is stored](../guides/storage.md): what a room holds, and why nothing is
+  ever deleted to make room.

package/docs/tutorials/02-join-a-house.md

@@ -0,0 +1,91 @@
+# Tutorial 2: join a team's house
+
+Someone runs a house and invited you. They gave you a file named `invite-<you>.env`. At the
+end of this tutorial your sessions ship into your own rooms in their house, under a
+password only you know.
+
+**You need:**
+
+- Node 24 or newer;
+- the invite file, received over a trusted channel: croc, a password manager, or a USB
+  stick. Not chat or email. **The file contains a password.**
+
+## 1. Install memhouse
+
+```bash
+npm install -g memhouse
+```
+
+On Linux with a distro-packaged Node, prefix with `sudo`. See
+[the install guide](../guides/install.md#eacces-on-install).
+
+## 2. Install from the invite
+
+```bash
+memhouse install --env invite-<you>.env
+```
+
+This reads the house's address, your member name and a starting password from the file.
+It then connects, checks that you can write to your rooms, and ships every session on
+this machine. Your rooms already exist and are named for you: `mem.<you>_messages`,
+`mem.<you>_sessions`, and so on. You hold one grant, on `mem.<you>_*`, and nothing else in
+the database.
+
+Then it **offers to change the password** to one only this machine knows. Say yes. The
+person who invited you set the starting password, and once you rotate it, theirs stops
+working. Then it deletes the invite file, which is spent.
+
+Scripted, with no terminal: `--yes` rotates without asking.
+
+## 3. Check who you are
+
+```bash
+memhouse whoami
+memhouse status
+```
+
+`whoami` names the credential in use and what it may do. You should be a **member**,
+not an administrator. `status` shows the connection, your row counts and freshness.
+
+## 4. Keep shipping
+
+```bash
+memhouse start                # shipper + dashboard, until the next reboot
+memhouse service install      # or: survive reboots (systemd --user / LaunchAgent)
+```
+
+Your dashboard is at http://localhost:4640. It reads the house, so it shows your
+sessions from every machine you install on, not just this one.
+
+## 5. More machines
+
+Every machine you own ships into the same rooms, and the `host` column tells them apart.
+The invite file is spent, so set up the next machine from this one's env file:
+
+1. Copy `~/.memhouse/env` to the new machine over a trusted channel, to any path, say
+   `~/mh.env`. It holds your connection and your new password.
+2. On the new machine, install from that copy:
+
+   ```bash
+   memhouse install --env ~/mh.env
+   ```
+
+   This installs and then deletes the copy. It does not offer to rotate: only an invite
+   file does, and rotating here would lock out your first machine.
+
+Do not copy `~/.memhouse/host.json`. It is the first machine's identity, and each machine
+mints its own.
+
+## 6. Read your teammates' memory
+
+Not yet. Nobody can read your rooms, and you cannot read theirs, until someone runs
+`memhouse share`. [Tutorial 3](03-share-your-memory.md) covers it from both sides.
+
+## When something goes wrong
+
+- **`Authentication failed`** right after install: the inviter may have re-issued your
+  invite, or you rotated and another machine still has the old password. `memhouse passwd`
+  sets a new one; then update the other machines.
+- **`invite file … no such file`**: check the path. The file is deleted only after a
+  successful install.
+- Anything else: `memhouse doctor`, then [Troubleshooting](../guides/troubleshooting.md).

package/docs/tutorials/03-share-your-memory.md

@@ -0,0 +1,96 @@
+# Tutorial 3: share your memory
+
+Two members of one house: `alice` and `bob`. Each owns their rooms, and neither can read
+the other's. In this tutorial, alice lets bob read one project's history, then everything,
+then takes it back. Bob reads it from his own agent.
+
+**You need:** two members of the same house. If you have one house of your own, see
+[Invite members](../guides/invite.md) to add a second.
+
+## 1. Alice shares one project
+
+On alice's machine:
+
+```bash
+memhouse share bob --only project=memhouse
+```
+
+What this does:
+
+- grants bob `SELECT` on exactly three of alice's rooms: `alice_sessions`,
+  `alice_messages` and `alice_tool_calls`;
+- adds row policies so that, in those rooms, bob sees only rows where
+  `project = 'memhouse'`.
+
+Bob gets nothing else. Alice's stats tables, `meta` and `events` stay closed to him, as
+does any room alice gains later.
+
+Other scopes work the same way:
+
+- `session=…`
+- `host=…`
+- `source=…` (an editor, as stored: `claude-code`, `codex`, …)
+- `folder=…`
+- `since=…` and `until=…` (dates)
+
+Before it creates the first policy, `share` checks how the server treats readers that
+have no policy of their own: alice, and anyone with a full share. On some server
+configurations, a table's first row policy blinds those readers to every row. On such a
+server, `share` refuses rather than lock alice out of her own rooms.
+
+## 2. Bob reads it
+
+Bob's credential can now see three of alice's rooms. From any ClickHouse client, or
+`/mem:sql` in bob's agent:
+
+```sql
+SELECT project, count() FROM mem.alice_messages GROUP BY project
+-- one row: memhouse
+
+SELECT count() FROM mem.alice_session_stats
+-- refused: bob holds no grant on it
+```
+
+A query that strays outside the scope returns nothing, or is refused for the tables bob
+was never granted. It never returns more than the scope.
+
+## 3. Alice widens it to everything
+
+```bash
+memhouse share bob
+```
+
+A **full share** with no `--only`. Bob can now read all of `mem.alice_*`, including the
+stats, `meta` (alice's other share records among it) and `events`. The command says so
+when it runs. Use a full share for someone you would hand your laptop to.
+
+Going back from full to scoped is the same `--only` command. It takes the wildcard grant
+back first, so a failure part-way leaves bob with less access, never more.
+
+## 4. See who can read what
+
+```bash
+memhouse share --list
+```
+
+This prints memhouse's own record of the shares: each user, full or scoped, and the scope.
+A grant someone made by hand in SQL does not appear.
+
+## 5. Take it back
+
+```bash
+memhouse share bob --revoke
+```
+
+This withdraws the grants first, then drops the row policies. If the revoke is refused
+part-way, the policies stay, so bob never ends up with an unfiltered share.
+
+## What sharing cannot do
+
+- **Recall what was already read.** Bob may have copied rows while he could read them.
+- **Write.** A share is read-only. Only alice writes into alice's rooms.
+- **End with a password change.** Grants belong to the user, not the password. To cut
+  bob off, revoke.
+
+More detail, including what a full share exposes and why scoped shares are table by
+table: [Share and revoke](../guides/share.md).

package/examples/01-local-one-machine/README.md

@@ -0,0 +1,99 @@
+# 01 — one machine
+
+The smallest memhouse: one person, one laptop, a ClickHouse in a local container. It shows
+the whole loop — a house, a shipping pass, the rows in it, a search that finds a past
+conversation — in about a minute.
+
+## What it does
+
+1. `memhouse deploy --local` starts ClickHouse in Docker or Podman, bound to `127.0.0.1`
+   only, with a generated password. It creates two accounts: an administrator, and **you**
+   as a member who holds `mem.<you>_*` and nothing else. Both credentials go into the
+   memhouse home's `env` file (mode 600); nothing is typed or shown.
+2. It installs memhouse against that house and starts a background shipper.
+3. `memhouse ship` runs one pass in the foreground.
+4. `memhouse status` shows what the house holds; `memhouse search` finds a session.
+
+The script ships two made-up sessions from [`../fixtures`](../fixtures/), never yours, and
+works in its own home (`~/.memhouse-example-01`), so an install you already have is left
+alone.
+
+## Needs
+
+- Node.js 24 or newer, and `npm install -g memhouse`
+- Docker or Podman, and port 8123 free (or set `HOUSE_PORT`)
+- No earlier `memhouse deploy --local` on this machine. The container and volume names are
+  fixed (`memhouse-clickhouse`, `memhouse-data`), so a second local house refuses to start.
+  If you have one, you already have this example's result; try [02](../02-existing-clickhouse/).
+
+## Run
+
+```bash
+./run.sh
+```
+
+| Variable | Default | |
+|---|---|---|
+| `MEMHOUSE_BIN` | `memhouse` | the command to run, e.g. `node ~/memhouse/bin/memhouse.js` |
+| `EXAMPLE_HOME` | `~/.memhouse-example-01` | this example's memhouse home |
+| `HOUSE_PORT` | `8123` | the local port ClickHouse binds |
+
+## What you should see
+
+Trimmed from a run on a Linux VM with Docker, ClickHouse 26.7 and memhouse 0.18.9:
+
+```
+== 1. a house: ClickHouse in a container, bound to loopback, plus the install
+  ✓ ClickHouse starting via docker on http://localhost:8123 (loopback only)
+  ✓ ClickHouse ready
+  ✓ member 'polat' holds mem.polat_* and nothing else; 'memhouse_root' administers the house
+  ✓ rooms for 'polat': polat_sessions, polat_messages, polat_tool_calls
+  ✓ installed
+  ✓ shipper started in the background (pid 617049) — loading your history now
+
+== 2. one shipping pass
+[memhouse] shipped 2 sessions (0 skipped) → 6 msg rows, 2 tool rows in 0.7s
+
+== 3. what the house holds
+  ✓ connected: http://localhost:8123 / mem as polat
+  ✓ house: 2 sessions, 6 messages (freshest ingest 2026-10-07 21:08:06 UTC)
+  ✓ fleet: 1 active writer(s)
+     polat@testbed-7edeca38       0.18.9   last ship 0m ago
+  ✓ shipper: running — daemon (pid 617049)
+
+== 4. find a past conversation
+claude-code:421460e4-5e66-4c1c-afa4-f1b198c28c25  claude-code  alpha  2026-10-07 19:07  (1 hit)
+  The deploy fails with ClickHouse error ACCESS_DENIED on INSERT. Why?
+```
+
+Three messages per session in the house, not four: the tool result is folded into the
+tool call it answers.
+
+To look around, start the dashboard in the example's home (pick another port if 4640 is
+taken by a real install):
+
+```bash
+MEMHOUSE_HOME=~/.memhouse-example-01 MEMHOUSE_PORT=4641 memhouse start
+```
+
+## Teardown
+
+```bash
+./run.sh --teardown
+```
+
+Stops the shipper (by the pid memhouse recorded), removes the container **and its data
+volume**, and deletes the example's home.
+
+## For real
+
+The same thing with your own sessions is two commands, in your default home:
+
+```bash
+npm install -g memhouse
+memhouse deploy --local
+```
+
+Every editor memhouse knows is read (`memhouse discover` lists what it finds first). Then
+`memhouse start` for the dashboard and `memhouse plugins install claude` to give your agents
+`/mem:recall` and the other skills.

package/examples/01-local-one-machine/run.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Example 01 — one person, one machine.
+#
+# A house in a local container, two made-up sessions shipped into it, then read back.
+# Runs in its own memhouse home, so an install you already have is never touched.
+#
+#   ./run.sh              build it and show it
+#   ./run.sh --teardown   stop the shipper, remove the container and its volume, delete the home
+#
+# Environment (all optional):
+#   MEMHOUSE_BIN    the memhouse command            (default: memhouse)
+#   EXAMPLE_HOME    where this example's install lives (default: ~/.memhouse-example-01)
+#   HOUSE_PORT      the local port ClickHouse binds  (default: 8123)
+set -euo pipefail
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+MH=${MEMHOUSE_BIN:-memhouse}
+mh() { $MH "$@"; }
+
+# Only this example's home speaks. An exported credential from another install would
+# otherwise outrank the home's own env file (flags > MEMHOUSE_* > env file).
+unset MEMHOUSE_URL MEMHOUSE_USER MEMHOUSE_PASSWORD MEMHOUSE_DB MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD
+export MEMHOUSE_HOME=${EXAMPLE_HOME:-$HOME/.memhouse-example-01}
+HOUSE_PORT=${HOUSE_PORT:-8123}
+
+if [ "${1:-}" = "--teardown" ]; then
+  mh stop || true
+  mh deploy --down --yes
+  rm -rf "$MEMHOUSE_HOME"
+  echo "example 01 removed"
+  exit 0
+fi
+
+mkdir -p "$MEMHOUSE_HOME"
+
+# Made-up sessions, and nothing else: the shipper reads only this directory.
+FIX="$MEMHOUSE_HOME/example-sessions"
+if [ ! -d "$FIX/projects" ]; then
+  echo "== writing two made-up Claude Code sessions to $FIX"
+  node "$HERE/../fixtures/make-sessions.js" "$FIX" me alpha beta
+fi
+export MEMHOUSE_EDITORS=claude MEMHOUSE_CLAUDE_ROOTS="$FIX"
+
+echo "== 1. a house: ClickHouse in a container, bound to loopback, plus the install"
+mh deploy --local --house-port "$HOUSE_PORT"
+
+echo
+echo "== 2. one shipping pass (deploy also started a background shipper; this one is in the foreground)"
+mh ship
+
+echo
+echo "== 3. what the house holds"
+mh status
+
+echo
+echo "== 4. find a past conversation"
+mh search ACCESS_DENIED
+
+echo
+echo "Done. Open the dashboard:  MEMHOUSE_HOME=$MEMHOUSE_HOME $MH start   (then http://localhost:4640)"
+echo "Remove everything:        $0 --teardown"

package/examples/02-existing-clickhouse/README.md

@@ -0,0 +1,121 @@
+# 02 — an existing ClickHouse
+
+You already run ClickHouse — a server of your own, your company's cluster, or ClickHouse
+Cloud — and want memhouse to keep its house there. You hold an account on it that can
+create users. This example builds a **member** account with it, installs as that member,
+and keeps only the member's credential on disk.
+
+## What it does
+
+1. `memhouse whoami --admin` checks that the admin credential really can create users and
+   grant, before anything is changed.
+2. `memhouse install --admin-user …` creates the member (default: your login name), grants
+   it `mem.<member>_*` and nothing else, creates its rooms, and verifies the install by
+   connecting **as the member**. The admin credential is used for this one command and not
+   saved (add `--keep-admin` if this machine should be able to invite people later).
+3. `memhouse ship --ensure-schema` creates any room or stat table that is missing — safe to
+   re-run, and the thing to run after an upgrade that adds one — then `memhouse ship`
+   ships two made-up sessions.
+4. `memhouse whoami` and `memhouse status` show the credential this machine now keeps and
+   what the house holds.
+
+## Needs
+
+- Node.js 24 or newer, and `npm install -g memhouse`
+- The ClickHouse HTTP endpoint, e.g. `https://ch.example.com:8443` (ClickHouse Cloud:
+  the HTTPS endpoint from the console). memhouse's CI runs on ClickHouse 25.11 and 26.7.
+- An account that can create users and databases and grant what it holds. A server's
+  first administrator qualifies: the `default` user of a fresh server, or the user the
+  Docker image creates with `CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1`. Step 1 tells you
+  whether yours does before anything changes.
+- The admin password where a tool can lend it to one command. It never goes on a command
+  line: `ps` and shell history would keep it.
+
+## Run
+
+```bash
+export MEMHOUSE_URL=https://ch.example.com:8443
+export MEMHOUSE_ADMIN_USER=default
+with-secret MEMHOUSE_ADMIN_PASSWORD=keychain:clickhouse-admin -- ./run.sh
+```
+
+No secret tool? Read it into this shell without echo:
+
+```bash
+read -rs MEMHOUSE_ADMIN_PASSWORD && export MEMHOUSE_ADMIN_PASSWORD
+./run.sh
+unset MEMHOUSE_ADMIN_PASSWORD
+```
+
+| Variable | Default | |
+|---|---|---|
+| `MEMHOUSE_URL` | (required) | the ClickHouse HTTP(S) endpoint |
+| `MEMHOUSE_ADMIN_USER` | (required) | the account that creates the member |
+| `MEMHOUSE_ADMIN_PASSWORD` | (required) | its password, lent by a secret tool |
+| `MEMBER` | your login name | the member to create |
+| `MEMHOUSE_BIN` | `memhouse` | the command to run |
+| `EXAMPLE_HOME` | `~/.memhouse-example-02` | this example's memhouse home |
+
+The same install without the script, giving the password on stdin instead of the
+environment:
+
+```bash
+printf '%s' "$PASSWORD" | memhouse install --url "$MEMHOUSE_URL" --admin-user default \
+  --member alice --admin-password-file - --yes
+```
+
+## What you should see
+
+Trimmed from a run against ClickHouse 26.7.1.1315 with memhouse 0.18.9 (the test endpoint is shown as `ch.example.com`):
+
+```
+== 1. whoami --admin: is this credential really an administrator?
+  ✓ admin at https://ch.example.com:8443 — administrator
+  credential from: MEMHOUSE_ADMIN_* environment
+  may create users:    yes
+
+== 2. install: build member 'polat' with the admin credential, then verify as the member
+  ✓ created ClickHouse user 'polat'
+  ✓ granted 'polat' mem.polat_* — their rooms and nothing else; async_insert pinned
+  ✓ verified as 'polat' with the member credential
+  ✓ installed
+  the admin credential was used for this install and not saved. To invite later:
+     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse invite <name> --url … --admin-user admin
+
+== 3. make sure every room and stat table exists, then ship once
+[memhouse] schema ensured (5 statements)
+[memhouse] shipped 2 sessions (0 skipped) → 6 msg rows, 2 tool rows in 0.2s
+
+== 4. whoami: the credential this machine keeps, and what it may do
+  ✓ polat at https://ch.example.com:8443 — member
+  may create users:    no
+
+== 5. status
+  ✓ house: 2 sessions, 6 messages
+  ✓ fleet: 1 active writer(s)
+```
+
+Step 2 generates the member password and writes it only to the home's `env` file (mode
+600). From 0.18.10 no command prints it; earlier versions showed it once on this step.
+
+## Teardown
+
+```bash
+./run.sh --teardown
+```
+
+Deletes the example's home. The member and its rooms stay in the house: dropping them is
+an administrator's decision. As the admin:
+
+```sql
+DROP USER polat;
+-- then each of mem.polat_sessions, _messages, _tool_calls, _meta, _events,
+-- _session_stats, _session_model_stats, _session_tool_stats
+```
+
+## For real
+
+Leave out the two fixture flags (`--editors claude --claude-roots …`) and the
+`EXAMPLE_HOME`, and every editor on the machine ships into the house. Your other machines
+join the same rooms by installing with the same member credential (`memhouse install --url
+… --user <member> --password …`, or an invite file — see [03](../03-team-house/)).

package/examples/02-existing-clickhouse/run.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Example 02 — point memhouse at a ClickHouse you already run.
+#
+# The admin credential builds a member account (rooms mem.<member>_*, one grant on exactly
+# those), the install is verified AS that member, and the admin credential is then dropped:
+# what stays on disk is the member's. The admin password never touches the command line.
+#
+#   with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- ./run.sh
+#   ./run.sh --teardown          stop anything this home started and delete the home
+#
+# Environment:
+#   MEMHOUSE_URL              required  the ClickHouse HTTP endpoint, e.g. https://ch.example.com:8443
+#   MEMHOUSE_ADMIN_USER       required  an account that can create users and grant
+#   MEMHOUSE_ADMIN_PASSWORD   required  its password — lent by with-secret, never typed into argv
+#   MEMBER                    optional  the member to create (default: your login name)
+#   MEMHOUSE_BIN              optional  the memhouse command (default: memhouse)
+#   EXAMPLE_HOME              optional  where this install lives (default: ~/.memhouse-example-02)
+set -euo pipefail
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+MH=${MEMHOUSE_BIN:-memhouse}
+mh() { $MH "$@"; }
+export MEMHOUSE_HOME=${EXAMPLE_HOME:-$HOME/.memhouse-example-02}
+
+if [ "${1:-}" = "--teardown" ]; then
+  mh stop || true
+  rm -rf "$MEMHOUSE_HOME"
+  echo "example 02 home removed. The member and its rooms stay in the house; dropping them is an admin's call."
+  exit 0
+fi
+
+: "${MEMHOUSE_URL:?set MEMHOUSE_URL to your ClickHouse HTTP endpoint}"
+: "${MEMHOUSE_ADMIN_USER:?set MEMHOUSE_ADMIN_USER to an account that can create users}"
+: "${MEMHOUSE_ADMIN_PASSWORD:?lend it with: with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- $0}"
+# A login name like "first.last" is not a ClickHouse user name memhouse accepts.
+MEMBER=${MEMBER:-$(id -un | tr -c 'A-Za-z0-9_\n' '_' | sed 's/^[^A-Za-z]*//')}
+# Only the admin variables and the URL come from outside. A member credential exported
+# by some other install would outrank this home's env file.
+unset MEMHOUSE_USER MEMHOUSE_PASSWORD MEMHOUSE_DB
+
+mkdir -p "$MEMHOUSE_HOME"
+FIX="$MEMHOUSE_HOME/example-sessions"
+[ -d "$FIX/projects" ] || node "$HERE/../fixtures/make-sessions.js" "$FIX" "$MEMBER" alpha beta >/dev/null
+
+echo "== 1. whoami --admin: is this credential really an administrator?"
+mh whoami --admin
+
+echo
+echo "== 2. install: build member '$MEMBER' with the admin credential, then verify as the member"
+# --editors/--claude-roots keep this example to the made-up sessions above. Drop both to
+# ship your real ones. --no-ship: nothing runs in the background; step 3 ships once.
+mh install --url "$MEMHOUSE_URL" --admin-user "$MEMHOUSE_ADMIN_USER" --member "$MEMBER" \
+  --editors claude --claude-roots "$FIX" --yes --no-ship
+
+# From here on the member credential in the env file is the only one in play.
+unset MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD
+
+echo
+echo "== 3. make sure every room and stat table exists, then ship once"
+# --ensure-schema only creates what is missing, as the member, and ships nothing; it is
+# safe to re-run, and the thing to run after an upgrade that adds a table.
+mh ship --ensure-schema
+mh ship
+
+echo
+echo "== 4. whoami: the credential this machine keeps, and what it may do"
+mh whoami
+
+echo
+echo "== 5. status"
+mh status