memhouse 0.18.9 → 0.18.11

package/docs/releases/v0.18.10.md

@@ -0,0 +1,226 @@
+# memhouse 0.18.10 — 2026-10-08
+
+A security release:
+
+- an admin password no longer has to go on the command line;
+- no command prints a member password;
+- a scoped share no longer reaches past its scope.
+
+Everyone on 0.18.x should upgrade.
+
+**No drill was run for this release; waived by the pilot (2026-10-08). The drill runs before 0.19.0.**
+
+```bash
+memhouse update        # or: npm install -g memhouse@latest, then memhouse update --no-install
+memhouse status        # every line a check mark
+```
+
+Nothing in the house changes: no migration, no new room, no re-ship. Machines on 0.18.9
+and 0.18.10 can ship into the same house side by side.
+
+## Security
+
+### An admin password never has to go on the command line (#14)
+
+The admin-assisted commands (`install --member`, `invite`, `passwd`, `convert`,
+`members`) now take the admin password from, in order:
+
+1. `--admin-password-file <file>`, a file holding the password (one trailing newline is
+   dropped), or `--admin-password-file -` to read it from stdin;
+2. `--admin-password <value>` (still accepted, with a warning; see below);
+3. `MEMHOUSE_ADMIN_PASSWORD` in the environment, which is how `with-secret` lends a secret
+   to one command;
+4. a credential this install already keeps, but only for the same admin user;
+5. a prompt, when there is a terminal to prompt on.
+
+```bash
+with-secret MEMHOUSE_ADMIN_PASSWORD=keychain:pilot/house-admin -- \
+  memhouse invite alice --url https://house.example.com --admin-user default
+printf '%s' "$ADMIN_PASSWORD" | memhouse invite alice --url … --admin-user default --admin-password-file -
+```
+
+Before this release, `--admin-user` as a flag switched every other source off. The only
+scriptable admin path therefore put the password on argv, where `ps` shows it for as long
+as the command runs and shell history keeps it. Found by O's sandbox rehearsal (finding 6).
+With no source and no terminal, the command stops and prints the three ways above instead
+of hanging or guessing.
+
+### An admin install no longer saves the admin credential (#14)
+
+`install --admin-user …` builds the member and then ships as the member. It used to write
+the admin credential into `~/.memhouse/env` as well. The help said it was saved; every
+agent-facing text said it never was. Now it is saved only with `--keep-admin`, or when
+the env file already keeps that same admin. Credentials already saved keep working.
+
+### A daemon never carries the admin credential (#14)
+
+- Service units (systemd, launchd) drop `MEMHOUSE_ADMIN_*` before they inline the env.
+- The shipper and the dashboard are started without it, even when the shell exported it.
+- `deploy --local` passes the ClickHouse password to `docker run` through the environment,
+  no longer as `-e CLICKHOUSE_PASSWORD=<value>` on its argv.
+
+A unit test now fails on any spawn or exec in the shipped code that puts a password on
+argv.
+
+### No command prints a member password (G23)
+
+`install --admin-user` used to show the generated member password once, on the terminal.
+It was already written to the env file, so the terminal copy served no one. It landed in
+scrollback and, through `/mem:access` and `/mem:admin`, in an agent's transcript, which
+memhouse ships into the house, where the archive is insert-only. (#20)
+
+- **Install and invite never print a generated member password.** It goes to the env file
+  (install) or the invite file (invite), and nowhere else.
+- **A failed install cleans up after itself.** If the grant fails after the member was
+  created, the run drops that member, so no account is left with a password nobody holds.
+- **`install --print-sql` and `invite --print-sql` print a placeholder,
+  `IDENTIFIED BY <member-password>`.** As printed, that line does not parse. The
+  administrator puts a quoted password they generate in its place, and the same password
+  goes into the env-file lines the command prints for the member. From `invite`, those
+  lines carry `MEMHOUSE_INVITE=1`, so the member's `install --env` offers to rotate it.
+  A `--member-password` given with `--print-sql` is not echoed.
+- **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
+    ClickHouse and checks each output against the real passwords.
+
+### A scoped share shares only what its scope filters (#13)
+
+`memhouse share <user> --only <scope>` granted `SELECT` on the member's whole pattern,
+`mem.<member>_*`, while its row policies covered only `sessions`, `messages` and
+`tool_calls`. A grantee scoped to one project could therefore read these in full:
+
+- `<member>_session_stats`: the opening prompt, folder, project and token totals of
+  every session in every project;
+- the model and tool stats;
+- `<member>_meta`, including the member's other `share:` records;
+- `<member>_events`;
+- any table the pattern matched later.
+
+Now:
+
+- **A scoped share is granted table by table,** on exactly the three filtered rooms.
+  Narrowing an existing full share to a scope takes the wildcard back first, so a failure
+  part-way leaves the grantee with less access, never more.
+- **`--revoke` withdraws the grants before it drops the row policies.** The old order
+  failed open: a `REVOKE` refused after the policies were gone left an unfiltered share.
+  A failed cleanup now keeps the policies unless every grant is confirmed withdrawn.
+- **`--only ""` and whitespace-only scopes are refused.** An unset `--only "$SCOPE"`
+  used to fall through to a full share.
+- **The permissive-server check before a scoped share runs.** Its probe table sat
+  outside the member's grant, so it was refused on every server and always reported
+  "could not verify".
+
+A full share (no `--only`) is unchanged: it reaches everything in `mem.<member>_*`, by
+design, and says so.
+
+**Action for existing scoped shares:** they keep their old wildcard until re-run. On the
+sharing member's machine, run `memhouse share <user> --only <scope>` again for each one;
+`memhouse share --list` shows them.
+
+## Deprecations
+
+| what | since | removed in | use instead |
+|---|---|---|---|
+| `--admin-password <value>` on the command line | 0.18.10 (2026-10-08) | **0.19.0** | `MEMHOUSE_ADMIN_PASSWORD` (via `with-secret`), `--admin-password-file <file>`, or `--admin-password-file -` |
+
+It still works in 0.18.x and prints one warning on stderr. Move scripts now.
+
+## Upgrading
+
+- **One machine:** `memhouse update`. The daemons restart on the new code.
+- **Upgraded by hand** (`npm install -g memhouse@latest`): run
+  `memhouse update --no-install` afterwards to restart the daemons.
+- **Several machines on one house:** no ordering is needed. This release changes no row
+  shape, no room and no shipper behaviour.
+- **Share owners:** re-run each scoped share once (above).
+- **Scripts and CI that pass `--admin-password`:** move to `MEMHOUSE_ADMIN_PASSWORD` or
+  `--admin-password-file` before 0.19.0.
+- **Scripts that read a member password from `install --admin-user` output:** read
+  `MEMHOUSE_PASSWORD` from the env file instead. The output no longer contains it.
+- **Scripts that run `--print-sql` output as is:** put a quoted password where
+  `<member-password>` stands. As printed, the line is refused by the server.
+- **If an admin credential is in `~/.memhouse/env`** and you did not mean to keep it,
+  remove the `MEMHOUSE_ADMIN_USER` / `MEMHOUSE_ADMIN_PASSWORD` lines. memhouse never
+  needs it to ship.
+
+## Also in this release
+
+- **The documentation standard** (#17). See [Documentation](#documentation) below. This
+  does change the package: it now also ships `docs/`, `examples/`, `AGENTS.md`,
+  `SECURITY.md` and `CHANGELOG.md`.
+
+These do not change the installed package:
+
+- **CI's tarball audit can fail now.** Its forbidden-file check was `! grep`, which
+  `set -e` never acts on, so it passed whatever the tarball held.
+- **gentar arena adoption** (#10). memhouse is now a gentar subject. Its suites are
+  `memhouse-house` and `memhouse-install`, kit v0.9.2, and they install from `npm pack`
+  exactly as a publish ships. The phase-1 check runs on GitHub-hosted runners on every
+  push and PR. Full arena runs need a self-hosted bench; the one used before the
+  repository went public was deregistered then.
+- **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`,
+  and none. The file source is covered by unit tests. CI runs both matrices against
+  ClickHouse 25.11 and 26.7.
+
+## Not in this release
+
+**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`
+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",
+mostly for pre-existing issues. Its pre-tag fixes are not all done, and this release was
+not held for them.
+
+Status of the 0.18.10 pre-tag list (`review-0.18.10-consolidated`):
+
+| item | what | status |
+|---|---|---|
+| B1 | scoped share reads past its scope | **landed** (#13) |
+| G3 | share re-scope or revoke fails open | **landed** (#13) |
+| G24 | `--only ""` is a full share | **landed** (#13) |
+| B7 | permissive-server probe never runs | **landed** (#13) |
+| B5 (part) | admin password in argv, units and daemons | **landed** (#14); `0600` enforcement on existing env/unit files is still open |
+| A1 | version bump incl. `package-lock.json` | **landed** here |
+| G23 | admin install and `--print-sql` print the member password | **landed** (#20) |
+| A2 | `/mem:recall` "recent sessions" uses a column the table lacks | deferred to 0.18.11 |
+| A3 | plugin `HOUSE.md` subagent queries lack the epoch filter | deferred to 0.18.11 (with the RC, which makes it matter) |
+| A4–A7 | RC log text, `update --no-install` checks, RC changelog notes | deferred to 0.18.11 (they are the RC's own surface) |
+| A8 | stale prose (ts interpolation, shrink, host id) | deferred to 0.18.11 |
+| G4 | `invite --url` connects with the stored credential to the invitee-facing URL | deferred to 0.18.11 (security) |
+| G26 | skills point at `../reference/HOUSE.md`; the file is `../../reference/HOUSE.md` | deferred to 0.18.11 |
+| G11 | an idle house's dashboard goes empty after the stats TTL | deferred to 0.18.11 |
+| GLM-F1 | a subagent file read before its first line is written re-sorts its siblings | deferred to 0.18.11 (with the RC) |
+
+## Documentation
+
+This release meets the documentation standard (#17):
+
+- a short README: what memhouse is, why, and how to install it;
+- `docs/`, with three tutorials and twelve guides;
+- `examples/`, four runnable setups from one machine to a self-hosted team house, each
+  with its own README;
+- an install and deploy section for agents in `AGENTS.md`.
+
+The npm package now ships `docs/`, `examples/`, `AGENTS.md`, `SECURITY.md` and
+`CHANGELOG.md`, so an installed copy carries its own manual. `change.log` (#19) lists
+every tag and what it changed.
+
+## Verification
+
+- `npm test` passes.
+- CI is green on `main` at the release commit: the syntax gate, unit tests, the
+  one-layout and invite matrices, and a headless e2e on ClickHouse 25.11 and 26.7.
+- No live house was touched to prepare this release.
+- **No drill was run for this release; waived by the pilot (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
+  its setup was refused by this session's permission layer, and the pilot chose to release
+  without it.

package/docs/releases/v0.18.11.md

@@ -0,0 +1,191 @@
+# memhouse 0.18.11 — 2026-10-10
+
+This release does three things:
+
+- **Sessions with subagents stop re-shipping.** A Claude Code session that used subagents
+  now ships only its new rows. Before, it re-sent itself whole on every pass, and that was
+  most of the house's write load.
+- **A security fix.** `invite` no longer sends a stored credential to whatever `--url` is
+  typed on the command line.
+- **The 0.18.10 pre-tag list is finished**, and the gentar test kit is bumped.
+
+**No drill was run for this release; waived (2026-10-08) under the pilot's 0.18.10 ruling. The drill runs before 0.19.0.**
+
+## Read this before upgrading
+
+**The first pass after the upgrade is a one-time bulk write.** It re-sends, whole and once,
+every stored session that has subagents; after that, those sessions ship only their new
+rows. Two things widen that first pass:
+
+- **Sessions whose subagents wrote recently.** A session whose subagent files are newer
+  than the house's record of it is read again even if it did not grow, because
+  `lastUpdatedAt` now counts subagent writes.
+- **Installs that share session files.** Two installs that ship the same session files
+  (two instances on one machine, or a synced directory) must be upgraded together. A
+  0.18.10 and a 0.18.11 number the same session differently, and each would fork it back
+  on every pass.
+
+**Where that write lands, and when to do it (2026-10-08):**
+
+- The pilot's machines (macminim, macbokum) ship to **zeo.memhouse.io**: VM 146 on arf,
+  ClickHouse 26.7.4.58.
+- It is **not** LXC 112 "memhouse-production"; that is an archive, not a live house.
+- zeo's data disk still sits on arf's degraded array. It was backed up to SSD on
+  2026-10-08 (data and access storage), but the disk itself has not moved.
+- **Upgrade those machines only once zeo's data disk is off the degraded array, or once
+  the array is repaired. Time it against the SSD moves.**
+- Any house on healthy storage can upgrade normally.
+
+```bash
+memhouse update        # then: memhouse status — every line a check mark
+```
+
+## Security
+
+### `invite` never sends a stored credential to `--url` (G4)
+
+`--url` is the invitee's address, typed on a command line. A typo, a tunnel, or somebody
+else's server received credentials it should never have seen:
+
+- the member's own credential, through the reachability probe and the read of its grants;
+- an admin credential the install keeps, through provisioning.
+
+The cause: `resolveConfig()` lets a flag outrank the env file, so the "configured house" URL
+the code used *was* `--url`.
+
+Now:
+
+- **A stored credential goes only to the house it was saved for.** That covers the
+  member's own, a `--keep-admin` admin, and a password read from the env file.
+- **`--url` gets an unauthenticated `/ping`**, only to confirm the invitee can reach it.
+- **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
+  nothing but a ping. On 0.18.10 the spy received two authenticated requests.
+
+**Action:**
+
+- If you ran `memhouse invite … --url <something unusual>` on 0.18.10 or earlier against a
+  host you do not control, rotate the member's password with `memhouse passwd`.
+- If an admin credential is kept in the env file and the same applies, rotate that too.
+
+## The re-ship fix (#21)
+
+Folded subagent rows were numbered by position, after the parent's turns. One new parent
+turn moved every one of them, so the session forked to a new epoch and was re-sent whole.
+Measured on a real house:
+
+- 1.07 M message rows written in 24 h, against 10.2 M in total;
+- one 6,120-line session stored 60 times in a day;
+- polat's house at about 19 M message rows for roughly 295 k real ones.
+
+What changed:
+
+- **Subagent rows get a numbering block of their own:**
+  `seq = 1,000,000,000 + slot × 100,000 + turn`, and the same for tool calls' `idx`.
+  `slot` is the subagent's rank by start time, so neither the parent growing, a subagent
+  growing, nor a new subagent appearing moves a stored row.
+- **A session without subagents is numbered exactly as before.**
+- **`seq` is sparse.** Count rows with `count()`, never `max(seq) + 1`.
+- **`ORDER BY seq` groups subagents.** Readers see the parent first, then each subagent's
+  turns together, in the order the subagents started. They used to be in agent-id order,
+  which is random.
+- **A parse too big for the blocks falls back to positional numbering:**
+  - a parent past 1e9 turns;
+  - a subagent past 100,000 turns;
+  - more than 32,949 subagents.
+
+  Positional numbering is correct, and merely re-ships whole as before.
+- **Subagent writes count as session activity.** A subagent that keeps running after its
+  parent goes quiet is shipped on the next pass.
+- **A subagent caught before its first line is written holds its session for one pass.**
+  It is then ranked by its real start time; it no longer ranks last and moves later. A
+  file that never gets a timestamped line stops holding the session after 10 minutes.
+- **Existing copies are not cleaned up.** Superseded epochs already in a house stay;
+  memhouse never deletes to make room. Reclaiming that space is a separate operator
+  decision, and no such cleanup may run on a house on degraded storage.
+
+## Also fixed
+
+- **The dashboard no longer goes empty on a quiet house (G11).** The stats tables carry a
+  one-day TTL and were refreshed only by passes that shipped something.
+  - The shipper now also refreshes them when the newest generation is over an hour old.
+  - The dashboard re-resolves its tables every five minutes, falling back to the live
+    rollup when a stats table is empty.
+- **The skills find their reference again (G26).** All five pointed at
+  `../reference/HOUSE.md`, a path that does not exist in the installed plugin; the file is
+  at `../../reference/HOUSE.md`.
+- **`/mem:recall`'s queries run (A2).**
+  - "Recent sessions" used a column the room does not have.
+  - The search now returns the `hit_seq` that the transcript read needs.
+  - The read takes its window by position, so the subagent blocks cannot break it.
+- **`HOUSE.md`'s subagent queries keep to the current parse (A3).** They used to double a
+  re-parsed session's subagent turns.
+- **An option that takes no value no longer swallows the next word (A6).**
+  `update --no-install yes` ran the install it was told to skip, and `share --revoke bob`
+  revoked nobody.
+- **`update --channel <name>` pins only a tag the registry has (A5).** Before, it never
+  wrote the pin at all.
+- **`update --no-install` restarts a tarball or nightly install.** That is the command
+  every nightly build prints for itself. On exactly those builds it stopped at "no
+  automatic update for this install" and exited 1, leaving the old shipper running old
+  code. It now restarts the daemons, runs any migration, and checks the schema; it needs
+  no channel.
+- **`update --no-install` (A6)** no longer prints "files updated", and it is no longer
+  refused on a project-dependency install.
+- **The epoch log line counts rows (A4).**
+- **Docs (A8): the host id is derived from the machine's own id**, as it has been since
+  0.18.6, so a reinstall keeps it. Stale prose about timestamps and `extra.turn` is fixed
+  too.
+
+## License notices
+
+**The dashboard now ships the license notices of what it bundles.** The built dashboard
+(`public/`) includes React, chart.js, lucide-react, react-markdown, tailwindcss and every
+other package it bundles. Their licenses (MIT, ISC) require the notice to travel with each
+copy, and minification strips it from the code.
+- `public/THIRD_PARTY_NOTICES.txt` is now generated at build time from the bundle's module
+  graph, and ships in the npm package.
+- CI fails a package that lacks it.
+
+Earlier published packages carried those copies without the notices.
+
+## Test infrastructure
+
+- **gentar kit v0.9.3 (#18).** In phase 1, `memhouse-house` is reported UNVERIFIED (bench
+  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.**
+  The fixture includes a superseded parse and a subagent block.
+
+## Pre-tag list (0.18.10 review): final status
+
+| item | where |
+|---|---|
+| A1 version bump | this release |
+| A2 `/mem:recall` queries | #22 |
+| A3 `HOUSE.md` subagent queries, epoch filter | #22 |
+| A4 epoch log count | #21 |
+| A5 `update --channel` validation | #21 |
+| A6 `--no-install` checks; switches swallowing values | #21 |
+| A7 upgrade-cost notes | #21, and this document |
+| A8 stale prose (ts, shrink, `extra` turn, host id) | #21 |
+| G4 `invite --url` and stored credentials (**security**) | #22 |
+| G26 skills' reference path | #22 |
+| G11 idle house's dashboard | #22 |
+| GLM-F1 unstamped subagent file | #21 |
+
+## Verification
+
+- **Unit tests:** `npm test` passes on main, 125 checks.
+- **CI:** green on ClickHouse 25.11 and 26.7.
+- **Matrices in a lab**, on ClickHouse 26.7.4.58 (production's version) and 26.7.1.1315.
+  They were run during #22 on main with #21 and #18 merged:
+  - skill recipe 18/18;
+  - invite 58/58;
+  - one-layout 62/62.
+- **Second looks:** agy (gemini-3.8-flash-high) on #21 and #22. Codex was at its daily
+  quota.
+- **Labs:** kept light, because arf's RAID is degraded. No live house was touched.

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).