memhouse 0.16.0 → 0.18.0

package/memhouse/delivery/INVITATION.md.tpl

@@ -0,0 +1,130 @@
+# You have been invited to a memhouse
+
+{{INVITER}} set up a **house** — a ClickHouse database where a team keeps its coding-agent
+memory — and made you a member of it. This page walks you from the file you were sent to a
+working install, and shows what you get.
+
+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. |
+| this page | the steps. Nothing secret in here. |
+
+Do it yourself, or hand this page to your coding agent. From the directory holding both
+files:
+
+```
+claude "Read MEMHOUSE-INVITATION.md and follow it. Ask me before each step that changes this machine."
+```
+
+Any agent that can run shell commands works the same way; the rules it must keep are at
+the end of this page.
+
+## 1. Install memhouse
+
+{{INSTALL}}
+
+On most Linux distros the global install needs `sudo`; if `npm` says `EACCES`, that is why.
+`memhouse --version` should print `{{VERSION}}`.
+
+## 2. Join the house
+
+From the directory holding `{{FILE}}`:
+
+```
+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
+working the moment install finishes, so a copy left in a chat is dead.
+
+## 3. Check it is working
+
+```
+memhouse status      # your rooms, how much is in them, the shipper's pulse
+memhouse doctor      # every line a check mark = healthy
+memhouse discover    # what this machine ships, and where each editor's sessions were found
+```
+
+`memhouse status` shows a session count that grows for a few minutes on a machine with
+history; the first pass ships everything you have. After that it ships new turns as they
+happen.
+
+## 4. What you own, and who can see it
+
+Your memory lives in five tables named for you inside `{{DB}}` — `{{DB}}.{{NAME}}_messages`,
+`{{DB}}.{{NAME}}_sessions`, `{{DB}}.{{NAME}}_tool_calls` and two bookkeeping tables — and you
+hold exactly one grant, on `{{DB}}.{{NAME}}_*`. Housemates cannot read your rooms, list
+them, or grant them to anyone; you cannot read theirs. `memhouse whoami --json` reads that
+grant back from the server. What can always see everything is the account that administers
+the ClickHouse, which is {{INVITER}}'s — the same as any database you use at work.
+
+Everything your editors write to disk ships verbatim: prompts, replies, tool calls and their
+arguments, including anything an agent ever pasted into a session. The house is as
+sensitive as your shell history. If some of your work should not go there, say so before
+shipping — see "which sessions ship" below.
+
+## 5. Things to try
+
+```
+memhouse search "the error you fixed last week"
+memhouse resume <session-id>          # prints the command that reopens that session
+memhouse plugins install claude       # /mem:recall, /mem:sql, /mem:house, /mem:access, /mem:admin
+```
+
+Then, inside Claude Code:
+
+```
+/mem:recall how did I set up the ClickHouse tunnel
+/mem:sql what did I spend on Opus this month
+/mem:house
+```
+
+Sharing is yours to give and take back, no operator involved:
+
+```
+memhouse share <housemate>                       everything you own
+memhouse share <housemate> --only project=<name> one project
+memhouse share --list
+memhouse share <housemate> --revoke
+```
+
+## Which sessions ship
+
+Everything memhouse finds on the machine — every supported editor, every Claude Code
+config directory. `memhouse discover` lists what it found and the variable that narrows
+each one. Two lines in `~/.memhouse/env` are the common case:
+
+```
+MEMHOUSE_EDITORS='claude'
+MEMHOUSE_CLAUDE_ROOTS='~/.claude-playbooks/<the one instance you mean>'
+```
+
+## If something refuses
+
+Every refusal says what to do next. The two you might meet: `EACCES` on install means
+`sudo`, and `needed rights this credential does not hold` means the grant on the server is
+narrower than the one memhouse issues — ask {{INVITER}} to run `memhouse install --print-sql
+--member {{NAME}}` and apply what it prints.
+
+## For an agent following this page
+
+You are installing memhouse for the person who handed you this file. Five rules; three of
+them exist because an agent broke them:
+
+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.
+2. **Run the commands as written, in order.** Do not substitute `CREATE USER`, `GRANT` or any
+   SQL of your own; there is nothing to fix on the server from this side.
+3. **Ask before `memhouse install --env`.** It rotates the credential, deletes `{{FILE}}`,
+   and starts shipping this machine's transcripts. The person decides when that happens.
+4. **A ✗ line is the end of that step, not an invitation to work around it.** Read the line
+   after it — every refusal names its remedy — do that or report it. `sudo` for `EACCES` is
+   the one you may apply yourself.
+5. **Report what `memhouse status` and `memhouse doctor` say**, verbatim, when you are done.
+   A green install is those two commands, not your summary of them.
+

package/memhouse/delivery/PROMPT.md

@@ -23,18 +23,25 @@ work that is not in your current context ("that session where…", "how did I so
 X before", "did we ever…", "what was I working on last week"), search memhouse
 FIRST. Only say you don't know after a search comes back empty.
 
-**How to query.** Prefer the installed skills when present: `/mem:ask` (answer a
-question from memory, with citations), `/mem:search` (full-text over messages),
-`/mem:sessions` (list/filter sessions), `/mem:sql` (free-form read-only SQL),
-`/mem:status` (what the system holds and its health), `/mem:share` and `/mem:users`
-(read-only sharing between users), `/mem:invite` (mint a new member — inviting comes
-before sharing), `/mem:hello` (introduce the system). Without skills, query directly.
+**How to query.** Prefer the installed skills when present:
 
-**Table names.** The house's rooms are three plain, shared tables — `messages`,
-`sessions`, `tool_calls` — in the connection's database. Everyone in the house writes
-into the same tables; `user_id` (server-stamped) says whose row it is and `host` says
-which machine. Query the whole house by default; add `WHERE user_id = '<name>'` for one
-person. **There is no `sessions_v` object** — the rollup is a saved query, and
+- `/mem:recall` — find past sessions and answer from them, with citations. This is the
+  one you want for almost every "have I seen this before" question.
+- `/mem:sql` — read-only SQL when the answer is a number: spend, model mix, tool
+  rankings, activity over time.
+- `/mem:house` — what the system is, whether it is shipping, what it holds, and who can
+  read it.
+- `/mem:access` — bring someone onto the server, or grant a housemate read-only access.
+- `/mem:admin` — server-wide administration; needs an administrator credential.
+
+Without skills, query directly.
+
+**Table names.** The rooms are `messages`, `sessions`, `tool_calls` in the connection's
+database — unless this is a shared house, where they carry the member's own prefix
+(`alice_messages`). `memhouse rooms` prints what yours are actually called; a bare
+`FROM messages` is not a table you have in a shared house. `user_id` (server-stamped)
+says whose row it is and `host` says which machine. To read across several members, UNION ALL over the rooms you hold — naming a room
+you do not hold is an error rather than a silent omission. **There is no `sessions_v` object** — the rollup is a saved query, and
 `memhouse sessions-query` prints it ready to drop into a `FROM (...) AS c`.
 
 **One session can be stored more than once.** The shipper never deletes: when an editor
@@ -66,12 +73,12 @@ the retained epochs are the only place that content still exists.
 **Rules.**
 - Memory is READ-ONLY for you: never INSERT/ALTER/DROP the ROOMS (sessions, messages,
   tool_calls) — ingestion belongs to the memhouse shipper alone. The one exception is
-  membership administration through the `memhouse` CLI: `/mem:invite` mints a user and
-  `/mem:share` grants read access, both via the tool, not by you writing to the rooms.
+  membership administration through the `memhouse` CLI: `/mem:access` mints a user and
+  `/mem:access` grants read access, both via the tool, not by you writing to the rooms.
 - Quote retrieved content as *the user's past sessions*, and cite the session_id
   when the user may want to dig deeper.
 - Other users' HOUSES (other databases on the same server) are readable only when
-  shared with this credential (`/mem:share` on their side). Query a shared house by
+  shared with this credential (`/mem:access` on their side). Query a shared house by
   qualified names — `polat.messages` — with the same CUR filter. An empty result
   means "nothing visible", not "nothing ever happened".
 - Do not paste credentials from `{{ENV_FILE}}` into responses, commits, or logs.

package/memhouse/delivery/kernel-install.md

@@ -80,8 +80,10 @@ user so the stamp cannot be skipped). Her machines are told apart by `host`.
 **A house is shared by its housemates.** The tables are common; `user_id` and `host` say
 who wrote what, and `WHERE user_id = 'alice'` is one person. The boundary is the
 DATABASE: a member of `mem` holds nothing on any other database, so two agencies on one
-kernel ClickHouse cannot read each other. The model is collaborative — housemates trust
-each other with the house; a separate house is the isolation mechanism.
+kernel ClickHouse cannot read each other. WITHIN a house, members hold their own rooms
+and nothing else — housemates are isolated from each other by grant, not by trust, and
+each can verify it with `SHOW GRANTS`. A separate house remains the boundary between
+groups that should not know of each other at all.
 
 Row policies are still the only way to share a *subset* of rows, which is owner-mediated
 and documented in `SHARING.md` — they are not how isolation works.

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: ask, search, browse, analyze, check, share, and invite across all 17 supported editors and machines, plus administration of the ClickHouse behind it. Skills install as /mem:hello, /mem:ask, /mem:search, /mem:sessions, /mem:share, /mem:invite, /mem:sql, /mem:status, /mem:users, and /mem:admin.",
-  "version": "0.16.0",
+  "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",
   "author": {
     "name": "Ramazan Polat"
   },

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

@@ -0,0 +1,173 @@
+# The house — connect, schema, and the three things that bite
+
+Read this before writing any query. Every `/mem:*` skill points here rather than
+repeating it, so there is one description of the store and it is either right everywhere
+or wrong everywhere.
+
+---
+
+## What this is
+
+A **house** is a ClickHouse **database** — on the user's machine, their server, or a
+hosted ClickHouse; memhouse runs no service of its own. Its **rooms** are tables —
+`sessions`, `messages`, `tool_calls` — and the server stamps who wrote every row. A
+house's grants reach nothing outside it.
+
+Every member's rooms are named for them — `mem.alice_messages`, `mem.alice_sessions`,
+`mem.alice_tool_calls` — and one grant covers exactly those: `ON mem.alice_*`. Housemates
+keep their own rooms beside yours and cannot read them, list them, or grant them onward;
+you cannot read theirs. `SHOW GRANTS` shows you the one line you hold. **A bare
+`FROM messages` names nothing you have** — the `q()` below prefixes room names with your
+member name for you, and `memhouse rooms` prints what yours are called.
+
+An **operator** owns the ClickHouse itself; an **admin credential** is what proves it.
+`memhouse whoami` says which you are holding.
+
+Rows arrive from a **shipper** that parses local transcripts from 17 editors. It only
+ever inserts. Nothing in memhouse runs an LLM over your data — these skills retrieve
+rows, and *you* read them.
+
+---
+
+## Connect
+
+**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no
+`env | grep MEMHOUSE`, no `set -x`. Anything printed becomes part of a transcript
+memhouse ships back into the house — the archive is insert-only, so a leaked credential
+cannot be withdrawn.
+
+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
+variable.
+
+```bash
+MH_ENV="${MEMHOUSE_HOME:-$HOME/.memhouse}/env"
+_u=${MEMHOUSE_URL-}; _s=${MEMHOUSE_USER-}; _p=${MEMHOUSE_PASSWORD-}; _d=${MEMHOUSE_DB-}
+set -a; [ -f "$MH_ENV" ] && . "$MH_ENV"; set +a
+[ -n "$_u" ] && MEMHOUSE_URL=$_u; [ -n "$_s" ] && MEMHOUSE_USER=$_s
+[ -n "$_p" ] && MEMHOUSE_PASSWORD=$_p; [ -n "$_d" ] && MEMHOUSE_DB=$_d
+if [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
+  echo "no memhouse house configured — run: memhouse install" >&2; exit 1
+fi
+
+q() {  # read-only by construction; every read path should use this
+  sed -E "s/([[:space:](]|^)(FROM|JOIN)[[:space:]]+(sessions|messages|tool_calls|meta|events)([[:space:];,)]|\$)/\1\2 ${MEMHOUSE_USER}_\3\4/g" \
+  | curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+    --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-$MEMHOUSE_USER}&readonly=1"
+}
+q <<'SQL'
+SELECT 1 FORMAT PrettyCompact
+SQL
+```
+
+`readonly=1` is a ClickHouse-side setting: even a mis-generated `DROP` is refused by the
+server, not by discipline.
+
+**The `sed` is what makes every query below work in both layouts** — write room names
+bare and it supplies the prefix when there is one. It rewrites only after `FROM`/`JOIN`,
+so a needle like `LIKE '%messages%'` is untouched, and `FROM yigit_messages` is left
+alone — the room name must follow whitespace, and there is none inside `yigit_messages`.
+With no prefix set it expands to nothing and the query passes through verbatim.
+
+It is spelled with `[[:space:]]` classes rather than `\b` because **BSD `sed` does not
+support `\b`**: on macOS the `\b` form matched nothing and sent the query through
+unprefixed. That fails loudly as `UNKNOWN_TABLE` rather than quietly reading wrong rows,
+which is the right way round — but it fails.
+
+**Reading a housemate's memory.** A share is `GRANT SELECT ON mem.<them>_*` — their
+rooms, not the database. `SHOW TABLES` lists exactly what you may read: your own rooms plus
+any shared with you. Name a housemate's rooms in full (`FROM yigit_messages`); the `q()`
+rewrite leaves an already-prefixed name alone, since applying yours would point at the
+wrong rooms. Say whose memory an answer came from.
+
+---
+
+## Schema
+
+**`messages`** — one row per turn.
+
+| column | meaning |
+|---|---|
+| `session_id` | `<source>:<adapter-local id>`, e.g. `claude-code:6b1f…` |
+| `seq` | position in the session, from 0 |
+| `source` | editor: `claude-code`, `codex`, `cursor`, … |
+| `host` | the machine, `<hostname>-<8 hex>` — random per install, not derived |
+| `ts` | when the turn happened (`DateTime64(3,'UTC')`) |
+| `role` | `user`, `assistant`, `system` |
+| `model`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens` | usage; **empty for several adapters** — see below |
+| `text` | the turn, **truncated at 50,000 chars** |
+| `text_ngram`, `text_word` | `MATERIALIZED lower(text)`, carrying the text indexes |
+| `project`, `folder` | where it happened; `folder` is what `resume` needs |
+| `user_id` | `MATERIALIZED currentUser()` — stamped by the server, unfakeable |
+| `origin` | `ship` or `import` |
+| `epoch` | which *parse* of the session this row belongs to |
+
+**`tool_calls`** — `session_id, seq, idx, source, host, tool_name, args, ts, project,
+folder, origin, epoch, user_id`. `args` is truncated at 20,000 chars. **There is no
+result column** — what a tool *returned* is not stored, and adapters truncate any preview
+of it to 300–500 chars inside `messages.text`.
+
+**`sessions`** — one metadata row per session: `name` (first user prompt, 120 chars),
+`source`, `host`, `project`, `folder`, `message_count`, timestamps, `extra`. Deliberately
+**not** epoch-keyed: latest write wins.
+
+`memhouse sessions-query` prints a self-contained per-session rollup (it carries its own
+`FINAL`) — prefer it over hand-joining.
+
+---
+
+## The three things that bite
+
+### 1. Epochs — a plain `SELECT` over-counts
+
+The shipper never overwrites a diverging parse. When a re-parse comes back shorter, or
+any overlapping turn hashes differently — which is what a **compaction** does to a long
+session — it writes the new parse under `epoch + 1` and keeps the old rows. So the same
+session can be present several times over.
+
+Reads must resolve to the current epoch. **Every counting or aggregating query needs
+this**, and the physical table name is the *raw* one, so nothing applies it for you:
+
+```sql
+WHERE origin != 'ship'
+   OR (session_id, user_id, epoch) IN (
+        SELECT session_id, user_id, max(epoch) FROM messages
+        WHERE origin = 'ship' GROUP BY session_id, user_id)
+```
+
+Measured on a real house: omitting it over-counted by **34%**. Drop it deliberately only
+when the question is about what a session said *before* it was compacted — superseded
+epochs are the one place that content still exists.
+
+### 2. Join on `(session_id, user_id)`, never `session_id` alone
+
+Two housemates can collide on an adapter-local session id. Every join, every `GROUP BY`
+that identifies a session, takes both columns.
+
+### 3. Escape before splicing, and lowercase the needle
+
+Search terms, session ids and user ids are arbitrary text going into single-quoted
+literals. Escape backslashes then single quotes (`\` → `\\`, `'` → `\'`) in **every**
+value. `O'Reilly` otherwise breaks the query, and crafted text could reshape it.
+
+The FTS columns are `lower(text)`, so lowercase what you look for:
+
+```sql
+WHERE text_ngram LIKE '%needle%'     -- substring, any length
+WHERE hasToken(text_word, 'needle')  -- whole word, faster on common terms
+```
+
+---
+
+## Known gaps — say these out loud rather than reporting a wrong number
+
+- **Cost is derived**, from `model` + tokens. Several adapters ship **no tokens at all**
+  (`kiro`, `vscode`, `zed`, and `cursor` on one of its two storage paths), so their cost
+  reads `$0` — which is *unknown*, not free. `memhouse doctor` names them.
+- **Per-message timestamps are interpolated** for most adapters — only the session bounds
+  are real. Hour-of-day and "peak time" charts inherit that.
+- **`text` stops at 50,000 chars**, tool `args` at 20,000. A missing tail is truncation,
+  not absence.
+- **Tool *results* are not stored at all.** If the question is "what did that command
+  print", the house cannot answer it.

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

@@ -0,0 +1,148 @@
+---
+name: access
+description: Bring someone onto this memhouse ClickHouse, or let them read your house — mint a new member with their own house and the env file their install needs, grant a housemate read-only access to yours, list who can currently read it, or revoke. Use when the user says "invite X", "add X to memhouse", "get my friend set up", "share my memory with X", "let X see my sessions", "who can read my memory", "stop sharing with X". Inviting comes BEFORE sharing — you can only grant a user who already exists. Read-only by construction on the sharing side: a share can never let anyone write to or delete your memory.
+user-invocable: true
+argument-hint: "invite <name> | share <name> | list | revoke <name>"
+allowed-tools: Bash
+---
+
+# /mem:access — who exists, and who may read
+
+Two things that look alike and are not:
+
+- **Invite** mints a ClickHouse *user* and their own *house*. Needs an administrator.
+- **Share** grants an existing user `SELECT` on *your* house. You can do this yourself.
+
+**Read `../reference/HOUSE.md` first** for the connection block. One rule dominates
+everything here: **a password must never enter this conversation.** memhouse ships this
+transcript into the house, and the archive is insert-only — a credential pasted here
+cannot be withdrawn.
+
+---
+
+## Invite — mint a member
+
+This runs the `memhouse invite` CLI and nothing else. **Do not hand-run `CREATE USER` /
+`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
+   `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_]*`;
+   refuse otherwise) and the **URL the invitee will reach the house at** — not localhost,
+   which is *their* machine. Do not ask about an admin credential yet; the next step
+   usually needs none. Default is their own house — omit `--db`.
+
+3. **Run it from the directory the file should land in** (step 4), bare first:
+
+   ```
+   memhouse invite <name> --url <url> [--db <shared-house>]
+   ```
+
+   `invite written: …` → go to step 4, and no secret touched this conversation.
+
+   Otherwise read WHICH refusal came back; they need different answers.
+
+   **"cannot reach `<url>` …"** — the address, not your privileges. A `deploy --local`
+   house is loopback-bound on purpose, so no LAN address reaches it and no invitee could
+   either. Ask for the address the invitee will actually use; do not retry with a guess.
+
+   **"`<user>` is a MEMBER of this ClickHouse, not an administrator"** — inviting needs
+   `CREATE USER` and `CREATE DATABASE`, which a member deliberately lacks. Ask which case
+   applies rather than assuming:
+
+   - *They run the ClickHouse.* Hand them the line to run THEMSELVES, with
+     `--admin-password` left OFF so it is prompted for — out of the process list and out
+     of shell history:
+
+     ```
+     memhouse invite <name> --url <url> --admin-user <admin>
+     ```
+
+     **You cannot run that yourself:** the prompt needs a TTY your Bash tool lacks, so it
+     refuses with "no TTY to prompt on" — and the fix is NOT `--admin-password`, which
+     would put the credential in this transcript.
+
+   - *Someone else runs it.* They cannot invite, and no flag changes that. Print the
+     statements for whoever administers the server — this contacts nothing:
+
+     ```
+     memhouse invite <name> --url <url> --print-sql
+     ```
+
+   **"house `<db>` already exists and holds N messages"** — STOP. That house is somebody's
+   memory. Report the row and writer counts and let the user choose: a different handle,
+   a different `--db`, or `--adopt` if sharing that house is genuinely the intent. Never
+   pass `--adopt` on your own initiative.
+
+4. **Put the file where they can attach it.** The CLI writes `invite-<name>.env` into the
+   current directory and the user sends it by hand — so run from their downloads
+   directory, or move it there. **Never leave it in a git repo.** Confirm it is present
+   and mode `600`, state the full path, and **never print its contents**.
+
+5. **Say whether the house was fresh** — `SELECT count() FROM <db>.messages` reads 0 for a
+   new one. Second line of defence behind step 3's refusal.
+
+6. **Write the message the user will send.** `invite` wrote TWO files beside each other:
+   `invite-<name>.env` (the credential, one-time) and `MEMHOUSE-INVITATION.md` (the steps,
+   nothing secret — install, verify, what they own, things to try). The guide does the
+   explaining, so the message is short: what memhouse is in a sentence; that the `.env` IS a
+   password (do not forward, do not paste in chat); open `MEMHOUSE-INVITATION.md` and follow
+   it. If `memhouse --version` shows a pre-release (a `-` in it), the invitee also needs the
+   tarball this build came from (`memhouse nightly --out …`); the guide says so and names it.
+
+   If they are REPLACING an existing credential, add `memhouse ship --full` — a plain
+   incremental pass skips sessions the new house has no record of, so their history would
+   not follow them.
+
+---
+
+## Share — let someone read your house
+
+Sharing runs the `memhouse share` CLI. **Do not hand-write `GRANT` or `CREATE ROW POLICY`
+for this** — partial sharing has four ways to go wrong quietly, and the command handles
+each one:
+
+```
+memhouse share <user>                          everything you own
+memhouse share <user> --only project=memhouse  just one project
+memhouse share <user> --only session=<id>      just one conversation
+memhouse share --list                          who can read it, and how much
+memhouse share <user> --revoke                 withdraw
+```
+
+Scopes: `session=`, `project=`, `folder=`, `host=`, `source=`, `since=`, `until=`, and
+they combine — `--only project=memhouse,since=2026-08-01`. Report back the counts it
+prints (`2121 of 22488 rows`), because that is what the person will actually see.
+
+**Say what a full share exposes** before running one: every session in the house, from
+every machine, project and editor, including anything ever pasted into one. If that is
+more than the user meant, `--only` is the answer, not a warning.
+
+**Never widen without being asked.** Re-running `memhouse share <user>` with no `--only`
+on someone currently scoped turns their partial share into a full one — the command says
+so, and you should surface that line rather than let it pass.
+
+### Why the CLI and not SQL
+
+- A permissive catch-all policy for everyone else is the obvious design and it **fails
+  open**: measured, a second scoped user saw all 22,500 rows instead of their 1,860.
+- Partial sharing depends on `users_without_row_policies_can_read_rows`, which is server
+  config, not a query setting, and whose default has moved between versions. The command
+  measures the behaviour before creating the first policy and refuses on a server that
+  would blindfold your existing readers.
+- Revoking the grant alone leaves the policies behind, and a later re-share silently
+  reinherits the old scope.
+- A policy on `messages` but not `tool_calls` leaks. All three rooms move together.
+
+If the command refuses because the server hides rows from unpolicied readers, relay its
+message — a full share still works there; only `--only` is unavailable until an admin
+sets that config.
+
+## Never
+
+Never accept a password typed into the conversation, and never print one. Never invent an
+admin credential. Never suggest storing one on disk. Never grant beyond `SELECT` — write
+access to your rooms is not a thing to hand out, and `ALL` would let the other side delete
+your memory. If the binary is absent, stop and say so rather than improvising the SQL.

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

@@ -8,10 +8,13 @@ allowed-tools: Bash
 
 # /mem:admin — operate the house as its administrator
 
-A member owns one database. An **administrator** owns the ClickHouse: every house, every
+A member owns a house, or rooms in one. An **administrator** owns the ClickHouse: every house, every
 account, every grant. This skill is the second one, and it is the only skill allowed to
 act outside the caller's own house.
 
+**Read `../reference/HOUSE.md` first** — connection, schema, and the traps every query
+here inherits.
+
 **An admin password must never enter this conversation.** memhouse ships this transcript
 into the house you are administering, so a password pasted here is a password published
 to the archive — and unlike a file you can delete, the archive is insert-only. Resolve
@@ -82,6 +85,32 @@ Reads worth knowing — reach for these before inventing SQL:
 | running queries | `SELECT query_id, user, elapsed, formatReadableSize(memory_usage) AS mem, substring(query,1,120) AS q FROM system.processes` |
 | unfinished mutations | `SELECT database, table, mutation_id, command, parts_to_do, latest_fail_reason FROM system.mutations WHERE NOT is_done` |
 
+### Sharing on someone else's behalf
+
+A member runs `memhouse share` against their own house. An administrator can do it for
+any house — useful when someone asks you to open theirs, or to audit what is open:
+
+```bash
+# what every house has opened up, server-wide
+adm "SELECT database, short_name, table, select_filter FROM system.row_policies ORDER BY database, short_name FORMAT PrettyCompact" "?readonly=1"
+adm "SHOW GRANTS FOR <user>"
+```
+
+To change a share, prefer running the member's own command with their credential over
+hand-writing SQL — the CLI handles the four traps (a permissive catch-all failing open,
+the server setting that decides whether unpolicied readers see anything, revoke leaving
+policies behind, and the three rooms drifting out of step). When you must do it as
+admin, mirror exactly what the CLI does: a policy on **all three rooms** or none, and
+`DROP ROW POLICY` on every room when withdrawing.
+
+**Dropping a house does not drop its row policies.** They persist as orphans, and a house
+later recreated under the same name silently inherits them. After any `DROP DATABASE`:
+
+```bash
+adm "SELECT short_name, table FROM system.row_policies WHERE database = '<db>'"
+# then DROP ROW POLICY <name> ON <db>.<table> for each
+```
+
 **Prefer a CLI verb over raw SQL wherever one exists.** `memhouse invite <name> --url …`
 provisions a member correctly — right grants, right pin, refuses a house that already
 holds someone's messages — and it takes `--admin-user`/`--admin-password`, so it works