memhouse 0.18.0 → 0.18.1

package/README.md

@@ -83,6 +83,7 @@ memhouse deploy --local | --down           stand up (or remove) a local house
 memhouse invite <name>                     mint a member + house, hand them one env file
 memhouse members [--db X]                  who is in a house, and what each can reach
 memhouse whoami [--admin]                  which credential is in play, and what it may do
+memhouse instance                          which memhouse this is: home, binary, house, rooms, scope, bindings
 memhouse rooms                             what your rooms are actually called
 memhouse share <user> [--only …|--revoke|--list]
                                            let a housemate read yours, in whole or in part
@@ -162,6 +163,18 @@ build sits on no tag and is never auto-updated; `update --check` says so and nam
 way forward. An invite from a house on a channel carries it, so the invitee follows it
 too.
 
+## Instances
+
+An instance is a home: an env file naming a house, the daemons shipping to it, and the
+playbooks whose sessions it ships (`MEMHOUSE_CLAUDE_ROOTS`). A machine can run several,
+each under its own `MEMHOUSE_HOME`, on different channels. `plugins install claude` from an
+instance installs into exactly the playbooks that instance ships and **binds** them: it
+writes `MEMHOUSE_HOME` and `MEMHOUSE_BIN` into each playbook's `settings.json` `env`, which
+Claude Code applies to every session there. So the `/mem:*` skills in a bound playbook read
+that instance's house and run that instance's binary, whatever the shell they were started
+from had. `plugins list` shows the binding; `plugins remove` takes it out. Everything else
+in `settings.json` is left as it was.
+
 ## Going back into a session
 
 `search` finds the conversation; `resume` hands you back into it.

package/bin/memhouse.js

@@ -438,6 +438,7 @@ Data         ship                 one incremental pass (--full | --loop [sec])
              search <terms…>      full-text search across all sessions
              resume <session-id>  print the command that reopens that session in its editor
              sessions-query       print the session rollup SQL for this credential
+             instance             which memhouse this is: home, binary, house, rooms, scope, daemons, bound playbooks
              rooms                what your rooms are actually called (--json)
              members              who is in a house and what each can reach (--db, admin)
              start | stop |       shipper loop + dashboard as background daemons
@@ -1235,6 +1236,10 @@ async function cmdInstall({ interactive }) {
   // deliberately for exactly this reason; install used to do nothing at all.
   if (displaces && shipperHealth().running) {
     const st = (() => { try { return require(path.join(REPO_ROOT, 'memhouse', 'service.js')).status(); } catch { return null; } })();
+    // Same server and database, different user, is a credential swap, not a house move —
+    // "old house" reads as data loss when nothing moved. A drill flagged the conflation.
+    const sameHouse = prior.MEMHOUSE_URL && sameEndpoint(prior.MEMHOUSE_URL, cfg.url) && (!prior.MEMHOUSE_DB || prior.MEMHOUSE_DB === cfg.db);
+    const whatMoved = sameHouse ? 'old credential' : 'old house';
     const viaService = String(shipperHealth().via || '').startsWith('service');
     if (viaService && st) {
       const cmd = st.kind === 'systemd'
@@ -1242,10 +1247,10 @@ async function cmdInstall({ interactive }) {
         : ['launchctl', ['kickstart', '-k', `gui/${process.getuid()}/com.memhouse.shipper`]];
       const r = spawnSync(cmd[0], cmd[1], { stdio: 'pipe', encoding: 'utf-8' });
       console.log(r.status === 0 ? ok('shipper restarted against the new house')
-        : warn('restart the shipper yourself, or it keeps writing to the old house:  memhouse service restart'));
+        : warn(`restart the shipper yourself, or it keeps writing under the ${whatMoved}:  memhouse service restart`));
     } else {
       const pid = pidOf('shipper');
-      if (pid) { try { process.kill(pid, 'SIGTERM'); console.log(ok(`stopped the shipper (pid ${pid}) — it was pointed at the old house`)); } catch { /* raced */ } }
+      if (pid) { try { process.kill(pid, 'SIGTERM'); console.log(ok(`stopped the shipper (pid ${pid}) — it was running under the ${whatMoved}`)); } catch { /* raced */ } }
       console.log('  start it against the new one:  memhouse start');
     }
   }
@@ -2417,7 +2422,19 @@ async function cmdPlugins() {
   const invocations = names.map((n) => `/mem:${n}`).join(', ');
   // --target overrides the discovery rather than joining it: given one, that is the only
   // directory touched.
-  const targets = flags.target ? [{ dir: flags.target, why: '--target' }] : claudeTargets();
+  // Targets: --target names one; otherwise an instance that ships specific playbooks
+  // (MEMHOUSE_CLAUDE_ROOTS) installs into exactly those — the plugin belongs where the
+  // sessions come from; failing both, every Claude config dir on the machine.
+  const binding = require(path.join(REPO_ROOT, 'memhouse', 'binding'));
+  const scope = require(path.join(REPO_ROOT, 'editors', 'scope'));
+  const icfg = resolveConfig();
+  const scoped = !flags.target && icfg.claudeRoots
+    ? scope.parseList(icfg.claudeRoots).map(scope.expandHome).map((d) => ({ dir: d, why: 'this instance ships it' }))
+    : null;
+  const targets = flags.target ? [{ dir: flags.target, why: '--target' }] : (scoped || claudeTargets());
+  // What the skills in a bound playbook run and read: this binary, this home.
+  const thisBin = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+  const boundLabel = (dir) => { const b = binding.boundTo(binding.readSettings(dir)); return b ? `bound to ${short(b.home)}` : 'unbound — sessions use whatever MEMHOUSE_HOME the shell has'; };
   // Whatever --target was given has to reappear in the advice, or pasting it installs
   // somewhere else than the directory just inspected.
   const self = `memhouse plugins install claude${flags.target ? ` --target ${flags.target}` : ''}`;
@@ -2427,7 +2444,7 @@ async function cmdPlugins() {
     if (!targets.length) { console.log(warn('no Claude Code config directory found')); return 0; }
     for (const t of targets) {
       console.log(isPluginInstalled(t.dir)
-        ? ok(`installed in ${short(t.dir)} (${t.why})`)
+        ? ok(`installed in ${short(t.dir)} (${t.why}) — ${boundLabel(t.dir)}`)
         : warn(`not installed in ${short(t.dir)} (${t.why})`));
     }
     if (!targets.some((t) => isPluginInstalled(t.dir))) console.log(`  install with: ${self}`);
@@ -2442,7 +2459,13 @@ async function cmdPlugins() {
     }
     const chosen = await chooseTargets(targets, 'Install');
     if (!chosen.length) { console.log(warn('nothing installed')); return 0; }
-    for (const t of chosen) console.log(ok(`installed ${names.length} skills into ${short(installPluginInto(t.dir))}`));
+    for (const t of chosen) {
+      console.log(ok(`installed ${names.length} skills into ${short(installPluginInto(t.dir))}`));
+      try {
+        binding.bind(t.dir, { home: HOME_DIR, bin: thisBin });
+        console.log(ok(`  bound: sessions under ${short(t.dir)} read ${short(HOME_DIR)} and run ${short(thisBin)}`));
+      } catch (e) { console.log(warn(`  not bound: ${e.message}`)); }
+    }
     console.log(`  loads as mem@skills-dir next session — invoke ${invocations}`);
     return 0;
   }
@@ -2458,6 +2481,8 @@ async function cmdPlugins() {
       // else's work.
       try { fs.rmdirSync(path.join(t.dir, 'skills')); } catch { /* not empty: leave it */ }
       console.log(ok(`removed ${short(path.join(t.dir, 'skills', 'mem'))}`));
+      try { if (binding.unbind(t.dir)) console.log(ok(`  unbound: MEMHOUSE_HOME/MEMHOUSE_BIN removed from ${short(path.join(t.dir, 'settings.json'))}`)); }
+      catch (e) { console.log(warn(`  could not unbind: ${e.message}`)); }
     }
     return 0;
   }
@@ -3335,6 +3360,53 @@ async function cmdWhoami() {
   return 0;
 }
 
+/**
+ * Bare `memhouse` with an invite file nearby: offer to process it. Returns null when there
+ * is nothing to offer (caller prints help), else the exit code of the install it ran or
+ * declined. Never touches the file's password: what it shows is the user, the house and
+ * the server, which the guide beside the file shows too.
+ */
+async function offerInvite() {
+  const inv = require(path.join(REPO_ROOT, 'memhouse', 'invitefile'));
+  // The current directory only. The guide says "from the directory holding the file", and
+  // reaching into ~/Downloads surfaced unrelated invitations from other houses — and could
+  // auto-join the wrong one under --yes. If they are somewhere else, they name the file.
+  const found = inv.findInvites([process.cwd()]);
+  if (!found.length) return null;
+  const described = found.map((f) => ({ ...f, ...inv.describeInvite((() => { try { return fs.readFileSync(f.file, 'utf-8'); } catch { return ''; } })()) }));
+  const usable = described.filter((d) => d.complete);
+  if (!usable.length) {
+    console.log(warn(`found ${found.length === 1 ? short(found[0].file) : `${found.length} invite files`} — not a complete invite (missing ${described[0].missing.join(', ')})`));
+    return null;
+  }
+  const cfg = resolveConfig();
+  const interactive = process.stdin.isTTY && flags.yes !== true;
+  console.log(ok(`found an invitation: ${short(usable[0].file)}${usable.length > 1 ? ` (and ${usable.length - 1} more)` : ''}`));
+  let pick = usable[0];
+  if (usable.length > 1) {
+    usable.forEach((d, i) => console.log(`  ${i + 1}) ${short(d.file)}   join ${d.url} as '${d.user}'`));
+    if (!interactive) { console.log('  several invitations here — name one:  memhouse install --env <file>'); return 1; }
+    const a = (await ask('Which one? (number, or n)', '1')).trim().toLowerCase();
+    const n = Number(a);
+    if (!Number.isInteger(n) || n < 1 || n > usable.length) { console.log('  nothing done.'); return 1; }
+    pick = usable[n - 1];
+  }
+  console.log(`  it joins ${pick.url}, house '${pick.db}', as member '${pick.user}'${pick.channel ? `, channel ${pick.channel}` : ''}.`);
+  if (cfg.stated && cfg.user) {
+    console.log(warn(`this machine already ships to ${cfg.url} as '${cfg.user}' — joining REPLACES that (the old config is kept as env.pre-install).`));
+  }
+  console.log('  Joining rotates the password to one only this machine knows, deletes the file, and starts shipping.');
+  if (!interactive) {
+    if (flags.yes === true) { flags.env = pick.file; flags.force = cfg.stated && cfg.user ? true : flags.force; return cmdInstall({ interactive: false }); }
+    console.log(`  Join with:  memhouse install --env ${path.basename(pick.file)}     (or: memhouse --yes)`);
+    return 0;
+  }
+  const a = (await ask(cfg.stated && cfg.user ? 'Replace the current house and join? (yes/no)' : 'Join now? (Y/n)', cfg.stated && cfg.user ? 'no' : 'Y')).trim().toLowerCase();
+  if (!(a === 'y' || a === 'yes' || (a === '' && !(cfg.stated && cfg.user)))) { console.log('  nothing done. Later:  memhouse install --env ' + path.basename(pick.file)); return 0; }
+  flags.env = pick.file; if (cfg.stated && cfg.user) flags.force = true;
+  return cmdInstall({ interactive: false });
+}
+
 async function cmdInvite() {
   const name = positional[0];
   if (!name) { console.log('usage: memhouse invite <name> --url <house-url> [--admin-user … [--admin-password …]] [--db <house>] [--out <file>] [--adopt] [--print-sql]'); return 2; }
@@ -3806,7 +3878,15 @@ async function cmdUninstall() {
   const cfg = resolveConfig();
 
   switch (cmd) {
-    case null: case 'help': console.log(HELP); break;
+    case null: {
+      // Bare `memhouse`. If an invite file is where the user is standing — or in their
+      // downloads — the likeliest reason they typed this is that they were handed it. Ask.
+      // Otherwise, the help screen as before. Nothing happens without a yes.
+      const code = await offerInvite();
+      if (code === null) console.log(HELP); else process.exitCode = code;
+      break;
+    }
+    case 'help': console.log(HELP); break;
     // `--version` and `-v` land here as flags, not as the `version` verb, so they used to
     // fall through to HELP: forty lines of help and exit 0 is not what --version means.
     case 'version': console.log(PKG.version); break;
@@ -3943,6 +4023,57 @@ async function cmdUninstall() {
       if (!au) console.log('  (run with --admin-user to be sure you are seeing every account)');
       break;
     }
+    case 'instance': {
+      // Which memhouse am I talking to? One screen: the instance, its binary, its house,
+      // its rooms, what it ships, its host, its daemons, and which playbooks are bound to
+      // it. A machine can run several instances; this is how they are told apart.
+      const cfg = resolveConfig();
+      const binding = require(path.join(REPO_ROOT, 'memhouse', 'binding'));
+      const scope = require(path.join(REPO_ROOT, 'editors', 'scope'));
+      const hostmod = require(path.join(REPO_ROOT, 'memhouse', 'host.js'));
+      const thisBin = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+      const name = binding.instanceName(HOME_DIR, readEnvFile().MEMHOUSE_NAME);
+      const host = (() => { try { return hostmod.read(HOME_DIR); } catch { return null; } })();
+      const daemons = { shipper: pidOf('shipper') || null, dashboard: pidOf('dashboard') || null };
+      const realHome = (() => { try { return fs.realpathSync(HOME_DIR); } catch { return HOME_DIR; } })();
+      const cands = new Map();
+      for (const d of scope.parseList(cfg.claudeRoots).map(scope.expandHome)) cands.set(d, d);
+      for (const t of claudeTargets()) cands.set(t.dir, t.dir);
+      const bound = [...cands.keys()].filter((d) => {
+        const b = binding.boundTo(binding.readSettings(d)); if (!b) return false;
+        try { return fs.realpathSync(b.home) === realHome; } catch { return b.home === HOME_DIR; }
+      });
+      let rooms = null; let counts = {};
+      if (cfg.stated && cfg.user) {
+        rooms = roomNames(cfg.user);
+        try {
+          // system.tables, not system.parts: a member holds no grant on the latter, and the
+          // former is filtered to what they may see. total_rows is approximate under merges
+          // and exact enough for "is anything in there".
+          for (const r of await chRows(cfg, `SELECT name AS table, total_rows AS n FROM system.tables WHERE database = ${sqlStr(cfg.db)} AND startsWith(name, ${sqlStr(`${cfg.user}_`)})`, { database: '' })) counts[r.table] = Number(r.n);
+        } catch { /* unreachable house: rooms still listed, counts absent */ }
+      }
+      const out = {
+        instance: name, home: HOME_DIR, envFile: ENV_FILE, binary: thisBin, version: PKG.version, channel: cfg.channel || null,
+        house: cfg.stated ? { url: cfg.url, db: cfg.db, member: cfg.user, adminCredential: !!cfg.adminUser, adminUser: cfg.adminUser || null } : null,
+        rooms: rooms ? [...ROOM_TYPES, ...META_TYPES].map((t) => ({ table: `${cfg.db}.${rooms.physical[t]}`, rows: counts[rooms.physical[t]] ?? null })) : [],
+        ships: scope.describe({ MEMHOUSE_EDITORS: cfg.editors, MEMHOUSE_CLAUDE_ROOTS: cfg.claudeRoots }),
+        host: host ? host.id : null, daemons: { ...daemons, dashboardUrl: daemons.dashboard ? `http://localhost:${cfg.port}` : null },
+        boundPlaybooks: bound,
+      };
+      if (JSON_OUT) { console.log(JSON.stringify(out, null, 2)); break; }
+      const line = (k, v) => console.log(`  ${k.padEnd(9)} ${v}`);
+      line('instance', `${name}   (${short(HOME_DIR)})`);
+      line('binary', `${short(thisBin)}   ${PKG.version}${cfg.channel ? `   channel ${cfg.channel}` : ''}`);
+      if (!out.house) { line('house', 'none configured — memhouse install'); break; }
+      line('house', `${cfg.url}   db ${cfg.db}   member ${cfg.user}   admin credential: ${cfg.adminUser ? `yes (${cfg.adminUser})` : 'no'}`);
+      line('rooms', out.rooms.map((r) => `${r.table}${r.rows === null ? '' : ` ${r.rows}`}`).join('  ·  '));
+      line('ships', out.ships);
+      line('host', host ? host.id : 'not minted yet (first ship mints it)');
+      line('daemons', `shipper ${daemons.shipper ? `running (pid ${daemons.shipper})` : 'stopped'}   dashboard ${daemons.dashboard ? `running (pid ${daemons.dashboard}) → http://localhost:${cfg.port}` : 'stopped'}`);
+      line('bound', bound.length ? bound.map(short).join(', ') : 'no playbook is bound to this instance — memhouse plugins install claude');
+      break;
+    }
     case 'rooms': {
       // What are my rooms called? One answer, in one place: named for the member, inside the
       // configured house. It resolves through roomNames(), so it cannot drift from what the

package/memhouse/binding.js

@@ -0,0 +1,81 @@
+// An instance's plugin is bound to the instance that installed it.
+//
+// A memhouse INSTANCE is a home: an env file naming a house, the daemons that ship to it,
+// and the playbooks (Claude Code config dirs) whose sessions it ships. Its /mem:* skills
+// belong in exactly those playbooks, and inside them they must read THAT house and run
+// THAT binary — a machine can carry two instances on two channels, and a bare `memhouse`
+// with a session-inherited MEMHOUSE_HOME would pick whichever the shell happened to have.
+//
+// Claude Code applies a settings.json `env` block to every session under a config dir.
+// So `plugins install` stamps two variables there, beside the skills it copies:
+//
+//   MEMHOUSE_HOME  the instance's home  — which house the skills read
+//   MEMHOUSE_BIN   the instance's binary — which memhouse the skills run
+//
+// Nothing else in the file is touched; other env keys survive; `plugins remove` takes the
+// two back out. Pure functions here, file I/O below them, both unit-tested.
+
+const fs = require('fs');
+const path = require('path');
+
+const KEYS = ['MEMHOUSE_HOME', 'MEMHOUSE_BIN'];
+
+function bindSettings(json, { home, bin }) {
+  const out = { ...(json || {}) };
+  out.env = { ...(out.env || {}), MEMHOUSE_HOME: home, MEMHOUSE_BIN: bin };
+  return out;
+}
+
+function unbindSettings(json) {
+  const out = { ...(json || {}) };
+  if (out.env) {
+    out.env = { ...out.env };
+    for (const k of KEYS) delete out.env[k];
+    if (!Object.keys(out.env).length) delete out.env;
+  }
+  return out;
+}
+
+function boundTo(json) {
+  const env = (json && json.env) || {};
+  return env.MEMHOUSE_HOME ? { home: env.MEMHOUSE_HOME, bin: env.MEMHOUSE_BIN || null } : null;
+}
+
+function settingsPath(dir) { return path.join(dir, 'settings.json'); }
+
+function readSettings(dir) {
+  try { return JSON.parse(fs.readFileSync(settingsPath(dir), 'utf-8')); } catch { return null; }
+}
+
+function writeSettings(dir, json) {
+  fs.writeFileSync(settingsPath(dir), `${JSON.stringify(json, null, 2)}\n`);
+}
+
+/** Stamp the binding into a config dir's settings.json; returns what was written. */
+function bind(dir, { home, bin }) {
+  const cur = readSettings(dir);
+  if (cur === null && fs.existsSync(settingsPath(dir))) throw new Error(`${settingsPath(dir)} is not valid JSON — not touching it`);
+  writeSettings(dir, bindSettings(cur || {}, { home, bin }));
+  return { home, bin };
+}
+
+function unbind(dir) {
+  const cur = readSettings(dir);
+  if (!cur || !boundTo(cur)) return false;
+  writeSettings(dir, unbindSettings(cur));
+  return true;
+}
+
+/**
+ * What an instance is called: MEMHOUSE_NAME if the env file sets one, else its home
+ * directory with the conventional `.memhouse-` prefix removed — `~/.memhouse-stage` is
+ * "stage", `~/.memhouse` is "default", `~/alice-sandbox/memhouse` is "memhouse".
+ */
+function instanceName(home, envName = '') {
+  if (envName) return envName;
+  const base = path.basename(String(home || '').replace(/[\/]+$/, ''));
+  if (base === '.memhouse') return 'default';
+  return base.replace(/^\.memhouse-/, '') || 'default';
+}
+
+module.exports = { bindSettings, unbindSettings, boundTo, bind, unbind, readSettings, KEYS, instanceName };

package/memhouse/delivery/INVITATION.md.tpl

@@ -8,7 +8,7 @@ You received two things:
 
 | file | what it is |
 |---|---|
-| `{{FILE}}` | **your credential.** One-time: install consumes it and deletes it. Treat it like a password until then. |
+| `{{FILE}}` | **your credential**, in this same folder. One-time: install consumes it and deletes it. Treat it like a password until then. |
 | this page | the steps. Nothing secret in here. |
 
 Do it yourself, or hand this page to your coding agent. From the directory holding both
@@ -21,6 +21,18 @@ claude "Read MEMHOUSE-INVITATION.md and follow it. Ask me before each step that
 Any agent that can run shell commands works the same way; the rules it must keep are at
 the end of this page.
 
+## 0. Find your credential
+
+The install needs `{{FILE}}`, which was sent alongside this page. Confirm it is here first —
+run this from the same directory, and if it prints the filename you are ready:
+
+```
+ls invite-*.env
+```
+
+If it is missing, it did not travel with this page; get it from whoever invited you before
+going on. Do not print its contents — the last line of it is a password.
+
 ## 1. Install memhouse
 
 {{INSTALL}}
@@ -30,12 +42,14 @@ On most Linux distros the global install needs `sudo`; if `npm` says `EACCES`, t
 
 ## 2. Join the house
 
-From the directory holding `{{FILE}}`:
+From the directory holding `{{FILE}}`, just run memhouse — it finds the invitation and asks:
 
 ```
-memhouse install --env {{FILE}}
+memhouse
 ```
 
+(or, without the question: `memhouse install --env {{FILE}}`)
+
 What that does, in order: connects to `{{URL}}` as `{{NAME}}`, **rotates your password to
 one only your machine knows**, creates your rooms, writes your config to `~/.memhouse/env`,
 deletes `{{FILE}}`, and starts shipping in the background. The password in the file stops
@@ -115,6 +129,9 @@ narrower than the one memhouse issues — ask {{INVITER}} to run `memhouse insta
 You are installing memhouse for the person who handed you this file. Five rules; three of
 them exist because an agent broke them:
 
+0. **Your credential is `{{FILE}}` in the directory this page is in.** If `Read
+   MEMHOUSE-INVITATION.md` is all you were given, `ls invite-*.env` beside it is the file
+   the steps refer to; confirm it is there before step 1.
 1. **Never print `{{FILE}}` or any `MEMHOUSE_*` value.** No `cat`, no `echo $MEMHOUSE_PASSWORD`,
    no `set -x`. This very session will be shipped into the house; a password printed here is
    a password archived.

package/memhouse/delivery/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mem",
   "description": "Conversation memory for AI agents over the memhouse typed ClickHouse store: recall past sessions and answer from them, run analytics, check the house, bring people in, and administer the server. Skills install as /mem:recall, /mem:sql, /mem:house, /mem:access, and /mem:admin.",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "author": {
     "name": "Ramazan Polat"
   },

package/memhouse/delivery/plugin/reference/HOUSE.md

@@ -36,6 +36,13 @@ rows, and *you* read them.
 memhouse ships back into the house — the archive is insert-only, so a leaked credential
 cannot be withdrawn.
 
+**Which memhouse.** `plugins install` stamps two variables into this config directory's
+`settings.json`, so every session here carries them: `MEMHOUSE_HOME` is the instance whose
+house these skills read, and `MEMHOUSE_BIN` is that instance's binary. **Every `memhouse …`
+command in these skills means `"${MEMHOUSE_BIN:-memhouse}"`.** A machine can run two
+instances on two channels; the bare name would be whichever the shell found first. Do not
+override either variable.
+
 Credentials resolve **flags > exported `MEMHOUSE_*` > `$MEMHOUSE_HOME/env`** (default
 `~/.memhouse/env`) — the same order the CLI uses. The dance below snapshots the
 environment first, because sourcing the file would otherwise clobber an already-exported

package/memhouse/delivery/plugin/skills/access/SKILL.md

@@ -26,7 +26,7 @@ This runs the `memhouse invite` CLI and nothing else. **Do not hand-run `CREATE
 `GRANT` with an admin password substituted into a command** — that burns the credential
 into a transcript on disk. The CLI passes it to one process and never echoes it.
 
-1. **Check the binary:** `command -v memhouse`. Absent → tell the user to
+1. **Check the binary:** `command -v "${MEMHOUSE_BIN:-memhouse}"`. Absent → tell the user to
    `npm install -g memhouse`. There is no in-skill fallback, on purpose.
 
 2. **Gather only two things:** the invitee's **name** (validate `[A-Za-z][A-Za-z0-9_]*`;

package/memhouse/delivery/plugin/skills/house/SKILL.md

@@ -32,6 +32,22 @@ stop:
 > `memhouse deploy --local` stands one up bound to loopback. Someone invited you?
 > `memhouse install --env invite-<you>.env`.
 
+## First: which memhouse this is
+
+Before anything else, run and show verbatim:
+
+```
+"${MEMHOUSE_BIN:-memhouse}" instance
+```
+
+One screen: the instance's name and home, the binary and channel, the house (server,
+database, member, whether an admin credential is present), the five rooms with row counts,
+what this machine ships, the host identity, the daemons, and which playbooks are bound to
+this instance. A machine can run several instances on different channels; this is how the
+user tells them apart, and how you know which house every answer below comes from. If the
+instance shown is not the one the user meant, stop and say so — the fix is launching
+under the right playbook, not overriding variables.
+
 ## The report
 
 Lead with the one-line verdict — *working and current*, *working but stale*, or *not

package/memhouse/flags.js

@@ -16,7 +16,7 @@ const COMMAND_FLAGS = {
   null: [], help: [], version: [],
   whoami: ['admin'],
   share: ['only', 'revoke', 'list'],
-  discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [], rooms: [], members: ['db','admin-user','admin-password'],
+  discover: [], stats: [], stop: [], doctor: [], 'sessions-query': [], rooms: [], instance: [], members: ['db','admin-user','admin-password'],
   status: [], start: [],
   onboard: ['url', 'user', 'password', 'db', 'port', 'no-ship', 'target', 'house-port', 'tag', 'local'],
   install: ['url', 'user', 'password', 'db', 'port', 'no-ship', 'env', 'print-sql', 'member',

package/memhouse/invitefile.js

@@ -0,0 +1,38 @@
+// An invite file found where the invitee is standing.
+//
+// The guide says "from the directory holding the file, run memhouse install --env <file>".
+// A person who just downloaded `invite-alice.env` and typed `memhouse` should not be shown
+// the help screen; they should be asked whether to join. This module finds candidate files
+// and reads what they promise; the CLI decides whether to ask, and install does the work.
+// Nothing here prints a value from the file — the URL, user and database are safe to show,
+// the password never is.
+
+const fs = require('fs');
+const path = require('path');
+const envfile = require('./envfile');
+
+const REQUIRED = ['MEMHOUSE_URL', 'MEMHOUSE_USER', 'MEMHOUSE_PASSWORD', 'MEMHOUSE_DB'];
+
+/** `invite-<name>.env` files in the given directories, first directory first. */
+function findInvites(dirs) {
+  const out = [];
+  for (const dir of dirs) {
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { continue; }
+    for (const n of names.sort()) if (/^invite-[A-Za-z0-9_]+\.env$/.test(n)) out.push({ file: path.join(dir, n), dir });
+  }
+  return out;
+}
+
+/** What the file promises, without the secret. */
+function describeInvite(text) {
+  const parsed = envfile.parse(String(text || ''));
+  const missing = REQUIRED.filter((k) => !parsed[k]);
+  return {
+    user: parsed.MEMHOUSE_USER || null, url: parsed.MEMHOUSE_URL || null, db: parsed.MEMHOUSE_DB || null,
+    channel: parsed.MEMHOUSE_CHANNEL || null, isInvite: parsed.MEMHOUSE_INVITE === '1',
+    complete: missing.length === 0, missing,
+  };
+}
+
+module.exports = { findInvites, describeInvite, REQUIRED };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memhouse",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "memhouse \u2014 agent conversation memory across 17 editors: parse-on-client shippers, a typed ClickHouse store with one set of rooms per member, kernel-agency install, and the agentlytics dashboard",
   "main": "bin/memhouse.js",
   "bin": {