memhouse 0.18.9 → 0.18.11

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/editors/claude.js

@@ -74,13 +74,18 @@ function getChats() {
     } catch { /* no index */ }
 
     // Scan all .jsonl files on disk (some may not be in the index)
-    let files;
-    try { files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')); } catch { continue; }
+    let names;
+    try { names = fs.readdirSync(dir); } catch { continue; }
+    const files = names.filter(f => f.endsWith('.jsonl'));
+    // A session with subagents also has a directory named for it; one without has none, so
+    // this listing is how the mtime check below stays free for the sessions it cannot help.
+    const sessionDirs = new Set(names.filter(f => !f.endsWith('.jsonl')));
 
     for (const file of files) {
       const sessionId = file.replace('.jsonl', '');
       const fullPath = path.join(dir, file);
       const entry = indexed.get(sessionId);
+      const subTouched = sessionDirs.has(sessionId) ? newestSubagentMtime(path.join(dir, sessionId, 'subagents')) : 0;
 
       if (entry) {
         // Use index metadata
@@ -89,7 +94,7 @@ function getChats() {
           composerId: sessionId,
           name: cleanPrompt(entry.firstPrompt),
           createdAt: entry.created ? new Date(entry.created).getTime() : null,
-          lastUpdatedAt: entry.modified ? new Date(entry.modified).getTime() : null,
+          lastUpdatedAt: latest(entry.modified ? new Date(entry.modified).getTime() : null, subTouched),
           mode: 'claude',
           folder: entry.projectPath || decodedFolder,
           encrypted: false,
@@ -107,7 +112,7 @@ function getChats() {
             composerId: sessionId,
             name: meta.firstPrompt ? cleanPrompt(meta.firstPrompt) : null,
             createdAt: meta.timestamp || stat.birthtime.getTime(),
-            lastUpdatedAt: stat.mtime.getTime(),
+            lastUpdatedAt: latest(stat.mtime.getTime(), subTouched),
             mode: 'claude',
             folder: meta.cwd || decodedFolder,
             encrypted: false,
@@ -195,7 +200,7 @@ function cleanPrompt(prompt) {
 // Parse one Claude session .jsonl into the adapter's message shape. When
 // `isSubagent` is set, each message is tagged `[subagent]` so folded subagent turns
 // are clearly attributed in the transcript.
-function parseSessionFile(filePath, isSubagent, agent = null) {
+function parseSessionFile(filePath, isSubagent, agent = null, info = null) {
   const messages = [];
   let lines;
   try { lines = fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean); } catch { return messages; }
@@ -205,7 +210,9 @@ function parseSessionFile(filePath, isSubagent, agent = null) {
   // cited, or told apart from a sibling's. An agent looking for the fork as its own session
   // concluded it was never shipped. Every turn now carries the agent's id, the description
   // the parent gave it, and its position within that subagent — in `extra`, which is not
-  // part of the line hash, so nothing already shipped is re-shipped for this.
+  // part of the line hash. The position is not only a label any more: the shipper numbers
+  // a subagent's rows from it (seq = block + turn, see subagentSeq in ship.js), so `turn`
+  // must count exactly the turns this parse keeps, in order.
   let turn = 0;
   const stamp = (m) => { if (agent) { m._agent = { ...agent, turn: turn++ }; } return m; };
 
@@ -228,6 +235,7 @@ function parseSessionFile(filePath, isSubagent, agent = null) {
     // time simply omit it.
     const _ts = obj.timestamp ? Date.parse(obj.timestamp) : undefined;
     const at = Number.isFinite(_ts) ? _ts : undefined;
+    if (info && info.firstTs === undefined && at !== undefined) info.firstTs = at;
 
     if (obj.type === 'user' && obj.message) {
       const content = extractContent(obj.message.content);
@@ -249,6 +257,10 @@ function parseSessionFile(filePath, isSubagent, agent = null) {
   return messages;
 }
 
+// How long a subagent transcript without a single timestamped line may hold back its
+// session (see getMessages). A real one gets its first line within seconds.
+const SUBAGENT_STAMP_GRACE_MS = 10 * 60 * 1000;
+
 function getMessages(chat) {
   const filePath = chat._fullPath;
   if (!filePath || !fs.existsSync(filePath)) return [];
@@ -262,30 +274,76 @@ function getMessages(chat) {
   const subagentsDir = path.join(filePath.replace(/\.jsonl$/, ''), 'subagents');
   const subFiles = subagentFiles(subagentsDir);
   const named = subFiles.length ? subagentNames(filePath) : new Map();
+  const folded = [];
+  let unstamped = null;
   for (const { file, workflow } of subFiles) {
     const id = path.basename(file).replace(/^agent-/, '').replace(/\.jsonl$/, '');
     const meta = named.get(id) || {};
     const agent = { id, description: meta.description || '', type: meta.type || (workflow ? 'workflow-subagent' : ''), file: path.basename(file) };
     if (workflow) agent.workflow = workflow;
-    const turns = parseSessionFile(file, true, agent);
+    const info = {};
+    const turns = parseSessionFile(file, true, agent, info);
     // A fork the parent never named (a Workflow-run agent, or a parent from before the
     // ids were reported) is described by its own first prompt — what it was told to do.
     if (!agent.description) {
       const first = turns.find((m) => m.role === 'user');
       if (first) { const d = String(first.content).replace(/^\[subagent\] /, '').replace(/\s+/g, ' ').trim().slice(0, 160); for (const m of turns) m._agent.description = d; }
     }
-    messages.push(...turns);
+    folded.push({ key: path.relative(subagentsDir, file), firstTs: info.firstTs, turns });
+    // A subagent caught before its first line is written has no start time, so it ranks
+    // last — and when its first line lands with an EARLIER timestamp than a sibling's, it
+    // moves, renumbers every sibling after it, and the session forks and re-ships whole
+    // (GLM-F1). So a fresh one defers the whole session to the next pass, when it has a
+    // time. Bounded by age: a file that never gets a timestamped line stops deferring after
+    // SUBAGENT_STAMP_GRACE_MS and ranks last, as before.
+    if (info.firstTs === undefined && !unstamped) {
+      let age = Infinity;
+      try { age = Date.now() - fs.statSync(file).mtimeMs; } catch { /* gone: nothing to wait for */ }
+      if (age < SUBAGENT_STAMP_GRACE_MS) unstamped = path.relative(subagentsDir, file);
+    }
+  }
+  // Each subagent gets a SLOT, and the shipper numbers its rows from that slot rather than
+  // from where they happen to land in this array (see subagentSeq in ship.js). The slot is
+  // the subagent's rank by when it started — the timestamp on its transcript's first line —
+  // because that is the one order a new subagent cannot disturb: it started after every
+  // subagent already on disk, so it ranks last. The file-name order this used to fold in
+  // does not have that property: agent ids are random, so a new fork sorted into the middle
+  // and pushed every later subagent's rows down, and a session with subagents re-shipped
+  // whole on every pass (one 6,120-line session was stored 60 times in a day). A file with
+  // no timestamp yet ranks after every one that has one; the path breaks ties.
+  folded.sort((a, b) => (a.firstTs === undefined) - (b.firstTs === undefined)
+    || (a.firstTs || 0) - (b.firstTs || 0) || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  folded.forEach(({ turns }, slot) => { for (const m of turns) m._agent.slot = slot; messages.push(...turns); });
+  if (unstamped) {
+    Object.defineProperty(messages, '_defer', { value: `subagent ${unstamped} has no timestamped line yet`, enumerable: false });
   }
 
   return messages;
 }
 
+/**
+ * When a session was last written, counting its subagents. The shipper's incremental skip
+ * compares `lastUpdatedAt` with what the house recorded, and a subagent writes only its own
+ * file: a background agent that runs on after its parent goes quiet left the parent's mtime
+ * (and the index's `modified`) where they were, so its turns shipped at the parent's next
+ * write, or never. Stat calls only, and only for a session that has a directory.
+ */
+function newestSubagentMtime(subagentsDir) {
+  let newest = 0;
+  for (const { file } of subagentFiles(subagentsDir)) {
+    try { newest = Math.max(newest, fs.statSync(file).mtimeMs); } catch { /* vanished mid-pass */ }
+  }
+  return Math.floor(newest);
+}
+function latest(a, b) { return b && (!a || b > a) ? b : a; }
+
 /**
  * Every subagent transcript under a session, wherever Claude Code put it:
  *   <session>/subagents/agent-<id>.jsonl                       — Agent tool forks
  *   <session>/subagents/workflows/wf_<id>/agent-<id>.jsonl     — Workflow-run agents
- * journal.jsonl and *.meta.json are bookkeeping, not transcripts. Sorted for a stable
- * fold order. On real data the workflow layer held 100 of 165 forks and shipped none.
+ * journal.jsonl and *.meta.json are bookkeeping, not transcripts. Sorted so the listing is
+ * deterministic; the fold ORDER is set by start time in getMessages, not by this.
+ * On real data the workflow layer held 100 of 165 forks and shipped none.
  */
 function subagentFiles(subagentsDir) {
   const out = [];

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