memhouse 0.18.8 → 0.18.10

package/bin/memhouse.js

@@ -147,7 +147,7 @@ function requireConfig(cfg, what) {
 }
 
 function childEnv(cfg, override = {}) {
-  return {
+  const env = {
     ...process.env,
     // Set only by the install path, which prints its own refusal for this case.
     ...(cfg._quietDenied ? { MEMHOUSE_QUIET_DENIED: '1' } : {}),
@@ -159,6 +159,11 @@ function childEnv(cfg, override = {}) {
       // environment would write into another member's rooms.
     ...override,
   };
+  // A daemon never needs the admin credential. Inherited from an exported shell variable
+  // it would sit in the shipper's and dashboard's environment for their whole lifetime.
+  delete env.MEMHOUSE_ADMIN_USER;
+  delete env.MEMHOUSE_ADMIN_PASSWORD;
+  return env;
 }
 
 function writeEnvFile(cfg) {
@@ -349,6 +354,34 @@ function netReason(e) {
 // Read without echoing. `onboard` and `setup` both prompt for the house password and
 // printed it back on the terminal — in a wizard whose whole audience is someone typing a
 // credential in front of whoever is in the room.
+// The admin password for `adminUser`: --admin-password-file (or - for stdin), then
+// --admin-password (warned), then MEMHOUSE_ADMIN_PASSWORD, then the stored credential
+// of that SAME admin, then a TTY prompt. null = none, and the caller has been told how
+// to give one without putting it on the command line. See memhouse/admin-secret.js.
+async function adminPasswordFor(adminUser) {
+  const as = require(path.join(REPO_ROOT, 'memhouse', 'admin-secret'));
+  const file = readEnvFile();
+  let r;
+  try {
+    r = as.resolveAdminPassword({
+      adminUser, flags, stored: { user: file.MEMHOUSE_ADMIN_USER, password: file.MEMHOUSE_ADMIN_PASSWORD },
+    });
+  } catch (e) { console.log(bad(e.message)); return null; }
+  // stderr: `members --json` and friends must emit nothing but JSON on stdout.
+  if (r.source === 'flag') console.error(warn(as.ARGV_WARNING));
+  if (r.password !== undefined) return r.password;
+  if (process.stdin.isTTY) {
+    const p = await askSecret(`  password for '${adminUser}'`);
+    if (p) return p;
+    console.log(bad('no password given'));
+    return null;
+  }
+  const lines = as.missingAdminPasswordHelp(adminUser);
+  console.log(bad(lines[0]));
+  for (const l of lines.slice(1)) console.log(l);
+  return null;
+}
+
 function askSecret(label, dflt = '') {
   if (!process.stdin.isTTY) return ask(label, dflt);
   return new Promise((resolve) => {
@@ -414,22 +447,23 @@ memhouse ${PKG.version} — agent conversation memory across 17 editors
 Setup        onboard              interactive wizard: discover → configure → ship → start
              install              scriptable setup (--url --user --password --db [--yes] [--no-ship])
                                   --print-sql            print the SQL, run it yourself
-                                  with admin: --admin-user --admin-password [--member NAME]
-                                  builds house + user + rooms + grants, then verifies as
-                                  the member. The admin credential IS written to the env
-                                  file (mode 600) so invite/members need no flags; delete
-                                  those two lines if you would rather pass it each time.
+                                  with admin: --admin-user NAME [--member NAME] builds the
+                                  member + grants, then verifies as the member. The admin
+                                  password comes from MEMHOUSE_ADMIN_PASSWORD (with-secret),
+                                  --admin-password-file FILE|- (stdin), or a prompt; plain
+                                  --admin-password works but shows in ps/history. It is NOT
+                                  saved unless --keep-admin (then invite needs no flags).
                                   --env FILE installs from an invite file (see: invite)
              invite <name>        mint a member and write the env file their install needs
-                                  (--url [--db NAME] [--out FILE]; --admin-user and
-                                  --admin-password only if this install keeps no admin
+                                  (--url [--db NAME] [--out FILE]; --admin-user — password
+                                  as for install — only if this install keeps no admin
                                   credential). They get rooms named for them, <db>.<name>_*,
                                   and one grant on exactly those. Refuses a name whose rooms
                                   already hold messages; --adopt takes them over (same
                                   person, new credential). Not an admin? --print-sql prints
                                   the plan to hand to whoever is.
              passwd               rotate this member's password + rewrite the env file
-                                  (admin-assisted: --admin-user --admin-password)
+                                  (admin-assisted: --admin-user, password as for install)
              setup                (re)write the connection config only (--yes = no prompts)
              discover             read-only preflight: editors, sessions, reachable ClickHouses
              uninstall            stop daemons + service, clear runtime state (asks; --yes).
@@ -752,10 +786,33 @@ function generatePassword() {
  * hand produces exactly what `--admin-user` would have produced. It is rendered from the
  * same templates provision.js applies, so the two cannot drift into different houses.
  */
-function memberSql(db, member, password) {
-  // The SAME plan adminBootstrap executes, rendered. Not a second description of it.
+function memberSql(db, member) {
+  // The SAME plan adminBootstrap executes, rendered. Not a second description of it — except
+  // the password: a printed plan carries a placeholder, never a real one (G23). Printed SQL
+  // lands in terminals, scrollback and agent transcripts, and memhouse ships transcripts.
   const { plan, render } = require(path.join(REPO_ROOT, 'memhouse', 'provision'));
-  return render(plan({ db, member, password }), { db, member });
+  return render(plan({ db, member, placeholder: true }), { db, member });
+}
+
+// The handoff lines that follow a printed plan: an env file for the member, with the
+// password left as the placeholder the plan used. `invite` marks it MEMHOUSE_INVITE=1, so
+// the member's `install --env` offers to rotate it to one only they know.
+function handoffLines({ url, db, member, invite }) {
+  const { PASSWORD_PLACEHOLDER } = require(path.join(REPO_ROOT, 'memhouse', 'provision'));
+  const lines = [
+    `-- Then put these lines in a file (mode 600), with the same password where ${PASSWORD_PLACEHOLDER}`,
+    '-- stands, and hand it over a channel you trust (croc, a password manager) — not chat:',
+    `--   MEMHOUSE_URL='${url}'`,
+    `--   MEMHOUSE_USER='${member}'`,
+    `--   MEMHOUSE_PASSWORD='${PASSWORD_PLACEHOLDER}'`,
+    `--   MEMHOUSE_DB='${db}'`,
+  ];
+  if (invite) lines.push('--   MEMHOUSE_INVITE=1');
+  lines.push('-- They install with:  memhouse install --env <that file>   (it deletes the file afterwards)');
+  if (flags['member-password'] !== undefined) {
+    lines.push('-- The --member-password you gave is not printed: use it where the placeholder stands.');
+  }
+  return lines.join('\n');
 }
 
 /**
@@ -813,17 +870,13 @@ async function adminBootstrap(cfg, admin) {
   } else {
     if (!password) {
       password = generatePassword();
-      // For a local install the password must be SHOWN — it is the user's only copy. For
-      // an invite it must NOT: the caller writes it to the credential file, and printing
-      // it here would land it in the terminal and, via /mem:access, in a transcript
-      // memhouse itself ships. admin.quiet is the invite path.
-      if (!admin.quiet) {
-        console.log('');
-        console.log(`  password for '${admin.member}':  ${password}`);
-        console.log(`  Shown once. It goes into ${ENV_FILE}; to change it later:`);
-        console.log(`     ALTER USER ${admin.member} IDENTIFIED BY '…'   then: memhouse setup --password …`);
-        console.log('');
-      }
+      // Never printed, on any path (G23). It used to be shown once on an install, "the
+      // user's only copy" — but install writes it to the env file, and an invite to the
+      // credential file, so the terminal never needed it. What the terminal gets ends up in
+      // scrollback and, via /mem:access and /mem:admin, in a transcript memhouse itself
+      // ships into the house. A run that fails before the password is written down drops
+      // the user it created (below), so no account is left behind with a password nobody
+      // holds.
     }
     try { await q(`CREATE USER ${admin.member} IDENTIFIED BY '${password.replace(/'/g, "\\'")}'`, { database: '' }); }
     catch (e) {
@@ -869,9 +922,15 @@ async function adminBootstrap(cfg, admin) {
   } catch (e) {
     console.log(bad(`could not grant the house to '${admin.member}': ${e.message}`));
     if (createdUser) {
-      console.log(`  ClickHouse user '${createdUser}' WAS created before this failed.`);
-      console.log(`  Continue once fixed:  memhouse install --member ${createdUser} --member-password '<the password above>' …`);
-      console.log(`  Or undo it as the admin:  DROP USER ${createdUser}`);
+      // This run made the user and nobody holds its password (it is never printed), so the
+      // only useful state is "not there": drop it, and the same command can simply be re-run.
+      try {
+        await q(`DROP USER IF EXISTS ${createdUser}`, { database: '' });
+        console.log(`  the ClickHouse user '${createdUser}' this run created was dropped — fix the cause and re-run`);
+      } catch (e2) {
+        console.log(`  ClickHouse user '${createdUser}' WAS created and could not be dropped (${String(e2.message).split('\n')[0]}).`);
+        console.log(`  Undo it as the admin:  DROP USER ${createdUser}   — then re-run.`);
+      }
     } else {
       console.log('  nothing was written');
     }
@@ -1029,6 +1088,7 @@ async function cmdInstall({ interactive }) {
   }
   let cfg = resolveConfig();
   const adminUser = flags['admin-user'];
+  if (adminUser === true) { console.log(bad('--admin-user needs a name, e.g. --admin-user default')); return 1; }
 
   // The house name is spliced unquoted into CREATE DATABASE and GRANT ALL ON <db>.* —
   // validate it HERE, on every install mode, not only where deploy happens to choose it.
@@ -1046,17 +1106,11 @@ async function cmdInstall({ interactive }) {
   if (flags['print-sql'] === true) {
     const member = resolveMemberHandle();
     if (!member) return 1;
-    const password = flags['member-password'] || generatePassword();
-    console.log(memberSql(cfg.db, member, password));
-    console.log(`-- Then, once that has run:`);
+    console.log(memberSql(cfg.db, member));
     // Only echo a URL that was actually STATED. --print-sql is the path where the house is
     // typically someone else's, run by someone else, and cfg.url falls back to
     // http://localhost:8123 — the one address the rest of the product refuses to guess.
-    // Handing it back as a copy-paste command carrying a live credential is worse than
-    // leaving a placeholder.
-    console.log(cfg.stated
-      ? `--   memhouse install --url ${cfg.url} --db ${cfg.db} --user ${member} --password '${password}'`
-      : `--   memhouse install --url <the house this SQL was run on> --db ${cfg.db} --user ${member} --password '${password}'`);
+    console.log(handoffLines({ url: cfg.stated ? cfg.url : '<the house this SQL was run on>', db: cfg.db, member, invite: false }));
     return 0;
   }
 
@@ -1064,11 +1118,22 @@ async function cmdInstall({ interactive }) {
   if (adminUser) {
     const member = resolveMemberHandle();
     if (!member) return 1;
+    // From a file, stdin, the environment or a prompt — never REQUIRED on argv.
+    const adminPassword = await adminPasswordFor(String(adminUser));
+    if (adminPassword === null) return 1;
     const built = await adminBootstrap(cfg, {
-      user: adminUser, password: flags['admin-password'] || '', member,
+      user: adminUser, password: adminPassword, member,
     });
     if (!built) return 1;
-    cfg = built;
+    // The admin credential is used for this install and NOT saved, unless asked
+    // (--keep-admin) or this env file already keeps that same admin (an operator seat).
+    // It used to be saved every time, which the help said and every agent-facing text
+    // (the install prompt, invite's own advice, /mem:admin) contradicted — and a saved
+    // admin password ends up wherever the env file goes.
+    const keepAdmin = flags['keep-admin'] === true || readEnvFile().MEMHOUSE_ADMIN_USER === String(adminUser);
+    cfg = keepAdmin
+      ? { ...built, adminUser: String(adminUser), adminPassword }
+      : { ...built, adminUser: '', adminPassword: '' };
   // BEFORE the env file and BEFORE the ship. INSTALL.md's contract is that the config is
   // written last, "after everything above has proved out", because a config left by a
   // failed install is read as truth by the next command. Placed after the write, a
@@ -1099,8 +1164,13 @@ async function cmdInstall({ interactive }) {
       console.log(`  every machine you install as '${cfg.user}' writes into the same rooms; this is what tells them apart`);
     }
     console.log(ok('installed'));
-    console.log('  adding a housemate later — the admin credential is in your env file, so no flags:');
-    console.log(`     memhouse invite <name> --url ${cfg.url}`);
+    if (cfg.adminUser) {
+      console.log('  adding a housemate later — the admin credential is kept in your env file, so no flags:');
+      console.log(`     memhouse invite <name> --url ${cfg.url}`);
+    } else {
+      console.log(`  the admin credential was used for this install and not saved. To invite later:`);
+      console.log(`     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse invite <name> --url ${cfg.url} --admin-user ${adminUser}`);
+    }
     printGettingStarted(cfg);
     await finishInvite(cfg);
     // The first ship loads the whole backlog; do it in the background so install returns
@@ -1114,7 +1184,9 @@ async function cmdInstall({ interactive }) {
   // authenticating as memhouse_root instead: the three flags did nothing, --yes satisfied
   // haveAll so no prompt asked who you were, and resolveConfig's default was used AS A
   // CREDENTIAL. Refuse rather than do something else silently.
-  const adminOnly = ['member', 'member-password'].filter((k) => flags[k] !== undefined);
+  // Every flag that only means something to the admin bootstrap. Left out, it was silently
+  // ignored on a member install (`--keep-admin` was — Codex P2 on #14).
+  const adminOnly = ['member', 'member-password', 'keep-admin', 'admin-password-file', 'admin-password'].filter((k) => flags[k] !== undefined);
   if (!adminUser && adminOnly.length) {
     console.log(bad(`--${adminOnly.join(', --')} ${adminOnly.length > 1 ? 'are' : 'is'} only read with --admin-user`));
     console.log('  Those flags provision a member, which needs house admin. Without them this');
@@ -3168,9 +3240,16 @@ async function cmdShare() {
   // today (the member has no grant option on the database) but with a raw ACCESS_DENIED
   // naming a privilege nobody can explain. Grant the rooms this member actually owns.
   const mine = roomNames(cfg.user);
-  // One grant on the member's own pattern: the shape the member holds, one level down
-  // (SELECT only). It reaches nothing a housemate wrote.
-  const shareTargets = [`${db}.${mine.pattern}`];
+  // A FULL share is one grant on the member's own pattern: the shape the member holds, one
+  // level down (SELECT only). It reaches nothing a housemate wrote — and, by design,
+  // everything of this member's, including the stat tables and any room added later.
+  const wildcard = `${db}.${mine.pattern}`;
+  // A SCOPED share is granted table by table: exactly the rooms its row policies filter,
+  // and nothing else. It used to take the wildcard too, and the policies covered only
+  // these three, so a grantee scoped to one project read every other project's opening
+  // prompt, folder and token totals straight out of <member>_session_stats, plus meta,
+  // events and whatever table the pattern would match next.
+  const scopedTargets = ROOM_TYPES.map((room) => `${db}.${mine.physical[room]}`);
 
   // Statements, not reads: this is the one command in the read family that writes, so it
   // does NOT go through the readonly connection the skills use.
@@ -3196,13 +3275,19 @@ async function cmdShare() {
   // re-share silently inherits the old scope. Measured — a re-granted user saw 2,121 rows
   // instead of the whole house, with nothing on any surface explaining the filter.
   if (flags.revoke === true) {
+    // Withdraw the grant FIRST, then the filters. The other order failed open: a REVOKE
+    // refused after the policies were dropped left the grantee with an unfiltered share.
+    try { for (const tgt of [wildcard, ...scopedTargets]) await run(`REVOKE SELECT ON ${tgt} FROM ${user}`); }
+    catch (e) {
+      console.log(bad(`could not revoke: ${netReason(e)}`));
+      console.log(`  Nothing else was changed: any row policies for '${user}' are still in place.`);
+      return 1;
+    }
     let dropped = 0;
     for (const room of ROOM_TYPES) {
       try { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, room)} ON ${db}.${mine.physical[room]}`); dropped++; }
       catch (e) { console.log(warn(`could not drop the policy on ${room}: ${e.message.split('\n')[0]}`)); }
     }
-    try { for (const tgt of shareTargets) await run(`REVOKE SELECT ON ${tgt} FROM ${user}`); }
-    catch (e) { console.log(bad(`could not revoke: ${netReason(e)}`)); return 1; }
     await houseMeta(cfg, `share:${user}`, `revoked ${new Date().toISOString().slice(0, 10)}`);
     console.log(ok(`revoked '${user}' — SELECT withdrawn and ${dropped} row polic${dropped === 1 ? 'y' : 'ies'} dropped`));
     console.log('  Dropping the grant alone would have left the policies, and a later re-share');
@@ -3211,9 +3296,12 @@ async function cmdShare() {
   }
 
   // ── grant ─────────────────────────────────────────────────────────────────────
-  const scopeRaw = flags.only !== undefined && flags.only !== true ? String(flags.only) : null;
+  const scopeRaw = flags.only !== undefined && flags.only !== true ? String(flags.only).trim() : null;
   let scope = null;
-  if (flags.only === true) { console.log(bad('--only needs a scope, e.g. --only project=memhouse or --only session=<id>')); return 1; }
+  // An EMPTY scope is a mistake, not a request for everything. `--only "$SCOPE"` with an
+  // unset variable used to fall through to a full share — the widest grant this command
+  // makes, from the flag whose whole purpose is to narrow it.
+  if (flags.only === true || scopeRaw === '') { console.log(bad('--only needs a scope, e.g. --only project=memhouse or --only session=<id>')); return 1; }
   if (scopeRaw) {
     try { scope = share.parseScope(scopeRaw); } catch (e) { console.log(bad(e.message)); return 1; }
   }
@@ -3251,24 +3339,47 @@ async function cmdShare() {
         made.push(room);
       } catch (e) {
         console.log(bad(`could not scope ${room}: ${e.message.split('\n')[0]}`));
-        for (const r of made) {
-          try { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, r)} ON ${db}.${mine.physical[r]}`); } catch { /* best effort */ }
-        }
-        console.log(`  NOTHING WAS GRANTED — '${user}' can read no more than before, and any`);
-        console.log('  filters this attempt created have been removed.');
+        // Do NOT drop what this attempt wrote. `OR REPLACE` may have just overwritten the
+        // filter of an EXISTING scoped share, and dropping it would leave that grantee's
+        // table grant unfiltered — failing open. A filter without a grant is inert, and the
+        // full-share and --revoke paths both clear leftovers.
+        console.log(`  NOTHING WAS GRANTED — '${user}' can read no more than before.`);
+        if (made.length) console.log(`  The filters written for ${made.join(', ')} are left in place; \`memhouse share ${user} --revoke\` clears them.`);
         return 1;
       }
     }
   }
 
-  try { for (const tgt of shareTargets) await run(`GRANT SELECT ON ${tgt} TO ${user}`); }
-  catch (e) {
+  // Full: the wildcard. Scoped: first take back any wildcard an earlier share left — it
+  // would reach straight past the filters — then grant the filtered rooms one by one.
+  // A failure part-way leaves the grantee with LESS than before, never more.
+  try {
+    if (scope) {
+      await run(`REVOKE SELECT ON ${wildcard} FROM ${user}`);
+      for (const tgt of scopedTargets) await run(`GRANT SELECT ON ${tgt} TO ${user}`);
+    } else {
+      await run(`GRANT SELECT ON ${wildcard} TO ${user}`);
+    }
+  } catch (e) {
     console.log(bad(`could not grant: ${netReason(e)}`));
-    // Filters without a grant are inert, but leaving them behind would make a later full
-    // share silently scoped — the case the widening path below exists to catch.
     if (scope) {
-      for (const room of ROOM_TYPES) {
-        try { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, room)} ON ${db}.${mine.physical[room]}`); } catch { /* best effort */ }
+      // Withdraw the grant, and drop the filters ONLY once that is confirmed. If any REVOKE
+      // is refused — the owner lost the grant option, a transient error — the grantee may
+      // still hold a table-level SELECT from an earlier scoped share, and dropping its
+      // filter would expose every row. Leaving a filter behind costs nothing: without a
+      // grant it is inert, and the full-share and --revoke paths both clear it.
+      let withdrawn = true;
+      for (const tgt of [wildcard, ...scopedTargets]) {
+        try { await run(`REVOKE SELECT ON ${tgt} FROM ${user}`); } catch { withdrawn = false; }
+      }
+      if (withdrawn) {
+        for (const room of ROOM_TYPES) {
+          try { await run(`DROP ROW POLICY IF EXISTS ${share.policyName(user, room)} ON ${db}.${mine.physical[room]}`); } catch { /* inert without a grant */ }
+        }
+        console.log(`  '${user}' was left with no access to your rooms — nothing wider than before.`);
+      } else {
+        console.log(`  Could not confirm '${user}' lost every grant, so the filters stay in place — whatever`);
+        console.log(`  '${user}' can still reach is filtered. Retry, or: memhouse share ${user} --revoke`);
       }
     }
     return 1;
@@ -3306,6 +3417,8 @@ async function cmdShare() {
       console.log(`  ${room.padEnd(11)} ${r[0].n} of ${all[0].n} rows`);
     } catch { /* counting is a courtesy */ }
   }
+  console.log('  Not shared under a scope: the stat tables, meta and events — they carry no');
+  console.log('  per-session filter, so a scoped reader gets none of them.');
   console.log(`  Widen to everything:  memhouse share ${user}`);
   console.log(`  Withdraw:             memhouse share ${user} --revoke`);
   return 0;
@@ -3321,7 +3434,10 @@ async function cmdShare() {
  * true = permissive, false = restrictive, null = could not tell.
  */
 async function probePermissive(cfg, db) {
-  const t = `_mh_probe_${process.pid}`;
+  // Inside the member's own pattern: the one place the one-layout grant lets them create a
+  // table and put a policy on it. A bare `_mh_probe_<pid>` sat outside it, was refused on
+  // every server, and turned this check into a permanent "could not verify".
+  const t = `${cfg.user}__mh_probe_${process.pid}`;
   const run = (sql) => ch(cfg, sql, { database: db });
   try {
     await run(`CREATE TABLE IF NOT EXISTS ${t} (x UInt8) ENGINE = MergeTree ORDER BY x`);
@@ -3576,19 +3692,11 @@ async function cmdInvite() {
   // statements adminBootstrap would run, so the person with the credential runs four
   // lines instead of installing anything. Nothing is contacted and nothing is written.
   if (flags['print-sql'] === true) {
-    const password = flags['member-password'] && flags['member-password'] !== true
-      ? String(flags['member-password']) : generatePassword();
     // memberSql prints its own header naming the house and the credential it needs; a
     // second one above it said the same thing twice, and in a shared house said the wrong
     // thing ("their own house" — they get rooms in a shared one).
-    console.log(memberSql(db, name, password));
-    console.log('-- Then send them these four lines — they are a credential, so use a channel');
-    console.log('-- you trust (croc, a password manager), not chat:');
-    console.log(`--   MEMHOUSE_URL='${url}'`);
-    console.log(`--   MEMHOUSE_USER='${name}'`);
-    console.log(`--   MEMHOUSE_PASSWORD='${password}'`);
-    console.log(`--   MEMHOUSE_DB='${db}'`);
-    console.log(`-- They install with:  memhouse install --url ${url} --user ${name} --password '…' --db ${db}`);
+    console.log(memberSql(db, name));
+    console.log(handoffLines({ url, db, member: name, invite: true }));
     return 0;
   }
 
@@ -3599,8 +3707,16 @@ async function cmdInvite() {
   // --admin-* wins. Otherwise the admin credential this install keeps beside its member
   // credential (a house you deployed or administer). Failing both, the member credential
   // itself is tried below — which works for whoever set the house up as its superuser.
-  let adminUser = flags['admin-user'] || cfg.adminUser || undefined;
-  let adminPass = flags['admin-password'] || (!flags['admin-user'] && cfg.adminPassword) || undefined;
+  if (flags['admin-user'] === true) { console.log(bad('--admin-user needs a name, e.g. --admin-user default')); return 1; }
+  let adminUser = (flags['admin-user'] ? String(flags['admin-user']) : '') || cfg.adminUser || undefined;
+  let adminPass;
+  if (adminUser) {
+    // --admin-password-file / --admin-password / MEMHOUSE_ADMIN_PASSWORD / the stored one
+    // for this same admin / a prompt. `--admin-user` as a flag used to switch the
+    // environment off, so the only scriptable path put the password on argv.
+    adminPass = await adminPasswordFor(adminUser);
+    if (adminPass === null) return 1;
+  }
   if (!adminUser) {
     const c = requireConfig(cfg, 'invite');
     if (!c.user) return 1;
@@ -3643,28 +3759,16 @@ async function cmdInvite() {
       console.log('  keeps one housemate out of another house.');
       console.log('');
       console.log('  If you RUN this ClickHouse — use the admin credential you created it with');
-      console.log('  (for a stock server that is `default`); memhouse never stores it, so pass it');
-      console.log('  per invite and it is used for one connection and discarded:');
-      console.log(`     memhouse invite ${name} --url ${url} --admin-user default`);
-      console.log('     (leave --admin-password off and it is prompted for, so it stays out of');
-      console.log('      your shell history and the process list)');
+      console.log('  (for a stock server that is `default`); memhouse does not store it, so give it');
+      console.log('  per invite — used for one connection and discarded, never on the command line:');
+      console.log(`     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse invite ${name} --url ${url} --admin-user default`);
+      console.log(`     memhouse invite ${name} --url ${url} --admin-user default      (prompts on a terminal)`);
       console.log('');
       console.log('  If SOMEONE ELSE runs it — you cannot invite, and no flag changes that.');
       console.log('  Print the statements and send them to whoever administers the server:');
       console.log(`     memhouse invite ${name} --url ${url} --print-sql`);
       return 1;
     }
-  } else if (adminPass === undefined) {
-    // Prompt rather than refuse. A password given as --admin-password lands in the
-    // process list for the life of the request and in shell history unless the caller
-    // remembered a leading space; asking for it keeps it in this process only.
-    // Non-TTY (an agent, CI) still gets the old refusal — there is nobody to ask.
-    if (!process.stdin.isTTY) {
-      console.log(bad('--admin-user given without --admin-password (no TTY to prompt on)'));
-      return 1;
-    }
-    adminPass = await askSecret(`  password for '${adminUser}'`);
-    if (!adminPass) { console.log(bad('no password given')); return 1; }
   }
 
   // WHERE to connect to provision. --url is the address the INVITEE will use — it may be
@@ -3844,12 +3948,15 @@ async function cmdPasswd({ quiet = false, forNext = null } = {}) {
         }
       }
     }
-    if (!adminUser || flags['admin-password'] === undefined) {
+    if (!adminUser || adminUser === true) {
       console.log(bad(`'${cfg.user}' cannot change its own password on this house (pre-0.11 member, or no access management).`));
-      console.log('  Rotate with an admin credential:  memhouse passwd --admin-user <a> --admin-password <p>');
+      console.log('  Rotate with an admin credential (password from MEMHOUSE_ADMIN_PASSWORD, --admin-password-file, or a prompt):');
+      console.log('     memhouse passwd --admin-user <a>');
       return 1;
     }
-    const via = { ...cfg, user: adminUser, password: flags['admin-password'] || '' };
+    const adminPassword = await adminPasswordFor(String(adminUser));
+    if (adminPassword === null) return 1;
+    const via = { ...cfg, user: adminUser, password: adminPassword };
     try { await ch(via, `ALTER USER \`${cfg.user}\` IDENTIFIED BY '${escPw}'`, { database: '' }); }
     catch (e) { console.log(bad(`could not rotate: ${e.message}`)); return 1; }
   }
@@ -3866,7 +3973,8 @@ async function cmdPasswd({ quiet = false, forNext = null } = {}) {
   console.log(ok(`password rotated for '${cfg.user}' and ${ENV_FILE.replace(os.homedir(), '~')} updated`));
   console.log('  restart anything that inlines the credential here:  memhouse update --no-install');
   console.log(warn('this rotated the ONE server credential — every OTHER machine you ship as'));
-  console.log(`  '${cfg.user}' now fails auth until it gets the new password (memhouse setup --password …).`);
+  console.log(`  '${cfg.user}' now fails auth until its env file gets the new password: copy the`);
+  console.log(`  MEMHOUSE_PASSWORD line from ${ENV_FILE.replace(os.homedir(), '~')} over a channel you trust.`);
   return 0;
 }
 
@@ -4100,7 +4208,8 @@ async function cmdUninstall() {
       const convert = require(path.join(REPO_ROOT, 'memhouse', 'convert'));
       const db = flags.db && flags.db !== true ? String(flags.db) : 'mem';
       const au = flags['admin-user'] && flags['admin-user'] !== true ? String(flags['admin-user']) : (cfg.adminUser || null);
-      const ap = flags['admin-password'] && flags['admin-password'] !== true ? String(flags['admin-password']) : (cfg.adminPassword || '');
+      const ap = au ? await adminPasswordFor(au) : '';
+      if (ap === null) { process.exitCode = 1; break; }
       if (!au) { console.log(bad('convert needs an admin credential: --admin-user/--admin-password (or the one this instance keeps)')); process.exitCode = 1; break; }
       const who = { ...cfg, user: au, password: ap };
       const only = flags.member && flags.member !== true ? String(flags.member) : null;
@@ -4188,7 +4297,8 @@ async function cmdUninstall() {
       // --admin-* wins; otherwise the admin credential this install keeps (a house you
       // deployed or administer). A member alone cannot read other accounts' grants.
       const au = flags['admin-user'] && flags['admin-user'] !== true ? String(flags['admin-user']) : (cfg.adminUser || null);
-      const ap = flags['admin-password'] && flags['admin-password'] !== true ? String(flags['admin-password']) : (cfg.adminPassword || '');
+      const ap = au ? await adminPasswordFor(au) : '';
+      if (ap === null) { process.exitCode = 1; break; }
       // Reading ANOTHER account's grants needs privilege; without it ClickHouse simply
       // returns fewer rows. Say so rather than presenting a short list as the whole truth.
       const who = au ? { ...cfg, user: au, password: ap } : cfg;

package/docs/README.md

@@ -0,0 +1,46 @@
+# memhouse documentation
+
+Start with a tutorial if memhouse is new to you. Use a guide when you know what you want
+to do. [`examples/`](../examples/README.md) holds runnable setups.
+
+## Tutorials
+
+Each one starts from nothing and ends with something working, in about ten minutes.
+
+| | |
+|---|---|
+| [1. Your first house](tutorials/01-first-house.md) | one machine: a local ClickHouse, your sessions shipped, the dashboard, search, `/mem:recall` |
+| [2. Join a team's house](tutorials/02-join-a-house.md) | someone invited you: install from the invite file, make the password yours, ship |
+| [3. Share your memory](tutorials/03-share-your-memory.md) | let a teammate read your house, all of it or one project, and take it back |
+
+## Guides
+
+One common operation each.
+
+| Guide | When you want to |
+|---|---|
+| [Install and onboard](guides/install.md) | install against a local, existing, or invited house; fix `EACCES` |
+| [Configuration](guides/configuration.md) | choose which editors and directories ship; run several instances; follow a channel |
+| [Update](guides/update.md) | stay current, and upgrade every machine of a house |
+| [Daemons and services](guides/daemons.md) | keep the shipper and dashboard running, across reboots |
+| [Invite members](guides/invite.md) | bring a teammate into a house you administer |
+| [Share and revoke](guides/share.md) | let someone read your rooms, scoped or whole |
+| [Admin password](guides/admin-password.md) | run an admin command without the password reaching `ps`, history, or a transcript |
+| [Search, resume and skills](guides/search-and-resume.md) | find an old session, reopen it, let an agent answer from history |
+| [How memory is stored](guides/storage.md) | houses, rooms, epochs, machine identity, what is never deleted |
+| [Operate a house](guides/operate.md) | members, migrations, moving a house, backups |
+| [Troubleshooting](guides/troubleshooting.md) | an editor ships nothing, daemons stop, a dashboard looks empty |
+| [Uninstall](guides/uninstall.md) | stop, forget the house, or remove everything |
+
+## Reference
+
+- `memhouse <command> --help`: every command's own usage. It always prints usage and
+  never runs the command.
+- [Release notes](releases/): what changed in each version, and what to do about it.
+- [`../memhouse/house/HOUSE.md`](../memhouse/house/HOUSE.md): the layout and the schema,
+  column by column.
+- [`../memhouse/DESIGN.md`](../memhouse/DESIGN.md): the design, and why it is shaped this
+  way.
+- [`../SECURITY.md`](../SECURITY.md): what holds, and what does not.
+- [`docs/design/`](https://github.com/agent-realm/memhouse/tree/main/docs/design) (in the
+  repository): designs captured before they are built.