@rayul/kordis 0.15.1 → 0.15.2

package/NOTICE

@@ -31,4 +31,4 @@ package and is not licensed with it.
     where no keychain is available.
   * `KORDIS_API_URL` points the CLI at a different host.
   * Error telemetry is off unless turned on, carries no identity, and is
-    described in the repository's CLAUDE.md.
+    described in the repository's `docs/security.md`, under "Error telemetry".

package/assets/AGENTS.md

@@ -0,0 +1,108 @@
+# packages/skills — the agent guidance both CLIs ship
+
+Markdown that an agent on a user's machine reads and acts on. It is not a pnpm
+package (no `package.json`, no scripts): the two CLIs copy it into their npm tarballs
+at build time, and their `setup` commands install it into the user's agent tools.
+These files are the product's user documentation; a reader who gets a wrong command
+from them runs it in front of a user.
+
+## Scope
+
+- `MEMGINEERING.md` — the memgineering hub. `memgineering setup` strips its
+  frontmatter and injects the body between `<!-- memgineering-start -->` and
+  `<!-- memgineering-end -->` into `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md` and
+  `~/.gemini/GEMINI.md` (and writes it as its own file under `~/.grok/rules/`). It is
+  in context for every session of every one of those tools.
+- `memgineering-*` — seven sub-skills (`memory` is the map from question to verb;
+  `recall`, `writing`, `rules`, `setup`, `registry`, `installing` carry the detail),
+  installed into each tool's `skills/` directory and loaded by description match.
+- `KORDIS.md` — the hub of the older `kordis` CLI, injected between
+  `<!-- kordis-start -->` and `<!-- kordis-end -->` by `kordis setup`.
+- `kordis-*` — six sub-skills. `kordis setup` installs five; `kordis-memory` stays
+  in the repo and is drift-checked but is not installed, because its commands are
+  registered only under `KORDIS_EXPERIMENTAL_MEMORY=1`.
+
+## Not in scope
+
+- The behaviour these files describe and the code that installs them:
+  `apps/memgineering` (`src/brand.ts`, `src/commands/setup.ts`) and `apps/cli`
+  (`src/brand.ts`, `src/commands/setup.ts`). Change the code there, the words here,
+  in the same change.
+- `apps/memgineering/assets/` and `apps/cli/assets/`: gitignored build output that
+  every build deletes and recopies. Never edit them.
+- Contributor documentation; these files are written for users' agents.
+
+## How the files ship
+
+- `pnpm -F memgineering build` copies `MEMGINEERING.md` and every `memgineering-*`
+  directory into `apps/memgineering/assets/` (`apps/memgineering/scripts/copy-skills.mjs`).
+  `pnpm -F @rayul/kordis build` copies this whole directory into `apps/cli/assets/`.
+- In both CLIs the hub file's presence in `assets/` is how the program tells a
+  published install from a source checkout; without it, `setup` reads this
+  directory directly.
+- A user's installed copy changes only when they upgrade the CLI and `setup` runs
+  again. A fix here does not reach anyone until a release.
+
+## Invariants
+
+- Every command, subcommand and flag a file names exists in the CLI that ships it.
+  `memgineering <verb> [<subcommand>] --flag` is checked against the program
+  `apps/memgineering` builds; `kordis <verb> --flag` against `kordis <verb> --help`.
+  Every backticked `snake_case` identifier in a kordis file must exist as a key or
+  string literal in the source of `packages/contracts`, `packages/harness-schema`,
+  `packages/memory-engine`, `apps/mcp` or `apps/cli`.
+- memgineering files spell the registry as `memgineering registry <verb>`. The flat
+  top-level aliases still work and are never taught.
+- The set of `memgineering-*` directories equals `BRAND.subSkills` in
+  `apps/memgineering/src/brand.ts`, in both directions, and the hub names every one.
+  A new sub-skill is a directory, a `BRAND.subSkills` entry and a hub mention.
+- Directory names are permanent. `setup` has no delete path, so a renamed sub-skill
+  leaves the old one on users' machines teaching the old surface.
+- The `MEMGINEERING.md` body (after frontmatter) stays under 5,000 characters with no
+  fenced code blocks. It sits two characters under the cap, so any addition moves
+  text into a sub-skill; phrases already moved into `memgineering-writing` are pinned
+  by the drift test and may not disappear.
+- `MEMGINEERING.md`'s `version:` frontmatter equals `apps/memgineering/package.json`
+  `version`; bumping the CLI means bumping this line. `KORDIS.md` carries its own
+  `version:` (0.2.0) that nothing ties to a package.
+- memgineering files are English only (no Hangul anywhere, triggers included), and
+  no shipped file contains an absolute home path (`/Users/...`, `/home/...`) or a
+  real person's name or conversation. The kordis files' descriptions carry Korean
+  trigger phrases on purpose.
+- The hosted connector URL in `memgineering-setup/SKILL.md` and in the hub equals the
+  one documented in `apps/mcp/README.md` and `HOSTED_CONNECTOR_URL` in the setup
+  command.
+- The hub and `memgineering-writing` both keep the rule that a stored fact is one
+  that was checked, not worked out.
+- A behaviour change in either CLI updates the matching file here in the same
+  change, and that release's changelog gets an `### Agent guidance` subsection: root
+  `CHANGELOG.md` (both language halves) for `KORDIS.md` and `kordis-*`,
+  `apps/memgineering/CHANGELOG.md` for the memgineering files.
+
+## Writing patterns
+
+- The hub routes; sub-skills explain. The hub holds only what must be true before
+  any skill loads, because it is paid for in every session.
+- A sub-skill keeps its frontmatter (`name`, `description`, `type`,
+  `allowed-tools`). The description says when to load it, lists trigger phrases and
+  says what it is not for — tools pick skills by that text alone.
+- When guidance has to override what a model assumes by default, state the negation
+  outright ("It does NOT wait for them") rather than only the fact.
+- Commands are written for the agent to run on the user's behalf, not as
+  instructions for the user to type; the reader may be someone who has never opened
+  a terminal.
+
+## Tests
+
+There is no test runner here; the suites that check these files live in the CLIs.
+
+- `pnpm -F memgineering test`, or `test:unit` (what CI's unit job runs) — both build
+  first, which recopies these files into `assets/`; `src/skill-drift.test.ts` covers
+  the memgineering files. Vitest run without that build checks whatever `assets/` an
+  earlier build left, not these files.
+- `pnpm -F @rayul/kordis test` — `src/__tests__/skill-doc-drift.test.ts` spawns
+  `kordis <verb> --help` through tsx for every verb the kordis files mention; it is
+  slow by design and has a two-minute per-test ceiling.
+- Read `Test Files N passed` for each package. A drift failure names the file and
+  the command or flag that does not exist; fix the guidance or the CLI, never the
+  test's verb list alone.

package/assets/MEMGINEERING.md

@@ -2,7 +2,7 @@
 name: memgineering
 description: Use whenever the user refers to something they told you before, asks what was decided, tells you something worth keeping, or settles something that should hold next time. The memory lives in their own folder and outlives this session; check it before answering from guesswork, and write to it when you learn something durable.
 type: skill
-version: 0.21.0
+version: 0.26.0
 ---
 
 # memgineering
@@ -83,6 +83,8 @@ at six skills, each of which loads on its own when its topic comes up:
 - `memgineering-registry` — the public layer
 - `memgineering-installing` — putting a package in their project, and updating it
 
+Not shell-only: ChatGPT and Claude.ai reach a hosted brain via connector `https://mcp.memgineering.com/mcp`.
+
 A host short on room lists a skill by NAME ONLY, no description — measured on
 Claude Code. When you cannot see what it covers, READ
 `<tool-home>/skills/memgineering-<name>/SKILL.md` before deciding it is empty.

package/assets/kordis-publishing/SKILL.md

@@ -80,10 +80,13 @@ feeds the `community-adapted` trust tier, and gives a small trending boost:
 | `--absorbs <slug>`      | `absorption` | folds the source in as one part                 |
 | `--remixes <slug>`      | `remix`      | recombines multiple sources                     |
 
-Unresolved sources (typo'd / unpublished slug) are **skipped fail-open** — the
-publish still succeeds and the response's `lineage.skipped` lists them so you
-can fix the slug or publish the source first. Declare lineage honestly; it is
-the registry's trust signal, not decoration.
+A source that does not resolve — a typo'd slug, or a package that is
+unpublished, deleted or private — **refuses the whole publish** with
+`usage_error` (exit 2), and `--dry-run` refuses it the same way, so a dry run
+catches a typo before anything is written. Fix the slug, or publish the source
+first, then push again. (Naming your own package as its source is skipped
+instead, and listed in the response's `lineage.skipped`.) Declare
+lineage honestly; it is the registry's trust signal, not decoration.
 
 ## Yanking a bad version (0.10.0+)
 
@@ -191,9 +194,13 @@ Possible verdicts:
 - `validation_failed` (exit 30) — fix every listed flag, re-dry-run.
 - `conflict` (exit 40) — slug taken; suggest a different slug (or pass
   `--slug` if first publish).
-- `ai_review_rejected` (exit 32) — EXPLAIN the rejection to the user. Do NOT
-  silently retry. Includes deterministic Stage-1 hits like
-  `curl_pipe_shell`, `aws_access_key`, `private_key_block`, etc.
+- Review rejection — never from a dry-run, which does not run the reviewer.
+  On the real push (step 3) a rejection is not an error: the push exits 0
+  and returns `status: "rejected"` with the reasons in `review.flags`
+  (`ai_review_rejected`, exit 32, is defined but never sent). EXPLAIN the
+  rejection to the user. Do NOT silently retry. Includes deterministic
+  Stage-1 hits like `curl_pipe_shell`, `aws_access_key`,
+  `private_key_block`, etc.
 - `rate_limited` (exit 31) — wait `retry_after_seconds`.
 - `not_authenticated` (exit 10) — `kordis login`, then retry.
 
@@ -245,10 +252,10 @@ User (push-back after adapting a judgment): "that decision rule we adapted from
    frontmatter; see "Publishing a judgment-pattern")
 2. kordis push ./judgment.md --type judgment-pattern --adapted-from <upstream/slug> --dry-run --json
 3. clean → drop --dry-run for the real push
-4. the response's `lineage.recorded` confirms the edge; if `lineage.skipped`
-   lists the source, the upstream slug was wrong or unpublished — fix it, or
-   publish the source first, then re-push. The edge gives the upstream
-   `community-adapted` credit and shows in its "Adapted by" graph.
+4. the response's `lineage.recorded` confirms the edge. A wrong or unpublished
+   upstream slug never gets this far: step 2's dry run already refuses it with
+   `usage_error` — fix the slug, or publish the source first. The edge gives the
+   upstream `community-adapted` credit and shows in its "Adapted by" graph.
 </example>
 
 <example>

package/assets/kordis-recommend/SKILL.md

@@ -46,7 +46,8 @@ Anonymous: works without login. Personalized signal rides on an opt-in
 `X-Kordis-Context` HTTP header (installed agent tools, top 3 CWD file
 extensions, framework hints from package.json/pyproject.toml/Cargo.toml,
 SHA-256-truncated hashes of installed slugs). Server uses it for in-flight
-re-ranking ONLY — never persisted (see CLAUDE.md "Telemetry / privacy").
+re-ranking ONLY — never persisted (see `docs/security.md` in the Kordis
+repository, "Search, context and addresses").
 
 ## Personalization opt-in
 

package/assets/memgineering-recall/SKILL.md

@@ -153,6 +153,11 @@ What you must not do is report what came back as everything the brain holds,
 which is exactly what a short answer looks like to anyone who does not read the
 line under it.
 
+When every card with a project came from ONE project and the brain holds
+others, recall says so (`scope_spread`: the project, and up to five others). If
+the user meant one of those, ask again with `--scope <that project>` — the note
+they want may be ranked just below a page full of the one the question named.
+
 ## Whether meaning was searched
 
 A hosted brain can match on meaning as well as words — the same idea in other
@@ -177,6 +182,12 @@ anything about what the user knows.
 If coverage says notes are missing entries, meaning was searched over part of
 the brain. Do not report that as a complete search.
 
+When meaning was used, each card also says what reached it — `matched`:
+`"words"`, `"meaning"`, or `"both"`. A `"meaning"` card (printed as _matched by
+meaning only_) shares no word with the question. That is right for a note in
+another language and wrong for one the model merely found nearby, so read its
+summary before you answer from it — never quote it back on the label alone.
+
 ## Two answers that are answers
 
 **Nothing matched.** Say so, and do not go read their folder yourself to
@@ -194,11 +205,14 @@ next brain, and three of them said it out loud. Reading another brain does not
 move the machine's pointer.
 
 **Cards that are not answers.** A card marked `not filled in yet` is one of the
-five `01_BASE/` files, still byte-for-byte what `init` wrote. Nobody has answered
+five `01_BASE/` files, still exactly what `init` wrote (line endings aside). Nobody has answered
 it, so it is evidence of nothing — do not quote it back as what they think. When
 every card carries that mark, recall says so above them (`--json`:
 `scaffolding: true`), and that is the moment to offer to fill them in rather
-than answer from them — see `memgineering-writing`.
+than answer from them — see `memgineering-writing`. At most two such cards come
+back per answer, plus any that is one side of a conflict, so both sides of a
+conflict always show; the rest are counted (`templates_withheld`), never
+silently dropped, and nothing anyone wrote is ever held back.
 
 The mark disappears once the user writes in the file. A filled-in base note is
 often the best answer in the brain: _who am I_, _what am I not allowed to do_,
@@ -219,8 +233,11 @@ On a hosted brain the folder counts too, as a name rather than a path: the CLI
 sends the folder's project — `owner/repo` from the git remote, or whatever
 `memgineering project` shows — and the server ranks what was asked about in
 that project first. The response says so itself: `ranked_by` gains `asked about
-in this project`, a card's reason reads `recalled 2× in this project`, and the
-footer names which project those words mean. Trust the footer over your
+in this project`, a card's reason reads `opened 1× · surfaced 2× in this project`
+(or `surfaced 2× …, never opened`), and the footer names which project those
+words mean. Only an open, or being the FIRST card of a recall, counts toward
+the order; a card merely listed further down is counted in words but earns
+nothing. Trust the footer over your
 assumption in the other cases as well — it says when this folder names no
 project (nothing was sent), and when the server does not rank by project yet
 (it was sent and ignored). A path never leaves the machine either way.

package/assets/memgineering-rules/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memgineering-rules
-description: Use when the user settles something they expect to hold next time — a colour they will not use, a step never to skip, a way things get named here — or when you want to see what already binds you in this folder. A decision does not have to be announced as a rule to be one. Triggers include "from now on", "always", "never", "don't do that again", "let's go with X from here", "we always do it this way", "what rules do I have". Covers remember --rule, rules, and what the before-edit hook shows.
+description: Use when the user settles something they expect to hold next time — a colour they will not use, a step never to skip, a way things get named here — or when you want to see what already binds you in this folder. A decision does not have to be announced as a rule to be one. Triggers include "from now on", "always", "never", "don't do that again", "let's go with X from here", "we always do it this way", "what rules do I have" — and, for moving one, "that should apply everywhere", "not just this project", "all my projects", "only in this repo from now on". Covers remember --rule, rules, rescope, and what the before-edit hook shows.
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
@@ -69,6 +69,20 @@ A hosted brain answers this too, and `--rule` writes to one land marked. The
 marking lives in the note's own frontmatter either way, so a brain that was
 pushed from a folder keeps every rule it had.
 
+**A rule saved from a chat app waits for the user.** ChatGPT, Claude.ai and
+other connectors can write notes, but not rules: a rule asked for there is
+kept as an ordinary note, and binds only once the user promotes it at a
+terminal. Promoting binds the note's own text as the chat wrote it — `--claim`
+changes the summary, not the words that bind — so they read it first with
+`memgineering open <id> --detail full` (the card alone shows only the title and
+summary, which a chat app may have rewritten), then `memgineering revise <id> --rule --claim "<what
+the note says>"`. Worded differently, it is a new rule: `memgineering remember
+"<the rule>" --rule`. A connector also cannot change or unmark an existing rule. Once
+promoted, the rule says where its words came from — `(written by the ChatGPT
+connector)` beside it in `memgineering rules` and in the before-edit hook, and
+`written_by` in `--json`. Treat it as their rule; the label says which surface
+it was first said on.
+
 **A rule also wins a tie in `recall` now.** Where an ordinary memory and a
 standing decision matched a query equally well, the decision is ranked first —
 the asymmetry being that a missed fact costs the reader some context, while a
@@ -85,12 +99,23 @@ alone earned — not that the top card is a rule, and not that it never could be
 since the engine noticing a note is decision-shaped is weaker evidence than its
 author saying it binds.
 
-One difference is worth knowing rather than discovering. The before-edit hook
-reads a brain **on this machine**, so on a machine pointed at a hosted brain it
-shows the local folder's rules, not the hosted brain's — a network call on the
-path of every file write is not a trade this makes. `memgineering rules` shows
-whichever brain the machine is pointed at; add `--local` to see what the hook
-will actually deliver.
+**Rules arrive in two budgets, not one list.** What a session is shown is the
+strongest few that hold everywhere, plus the strongest few scoped to the project
+it is standing in — ten in total, and each half gives its unused room to the
+other, so a brain with nothing scoped still fills the list. Rules scoped to a
+DIFFERENT project are not shown to an agent working here at all; they bind
+there. `memgineering rules` lists them separately under "scoped to other
+projects", which is the one place to notice a scope with a typo in it — such a
+rule binds nowhere and would otherwise appear nowhere.
+
+Before the split there was one list ranked by use, and it did not work: measured
+in a real repository, every slot went to rules about other things and a rule
+written that morning about that project's own layout ranked 49th of 54.
+
+The before-edit hook and `memgineering rules` read the same brain — the hosted
+one when this machine is pointed at it, the folder on disk otherwise — so what
+the hook will deliver is what the command shows. Add `--local` to read the
+folder on this disk specifically.
 
 ## What the user's agent actually sees
 
@@ -135,11 +160,30 @@ a long list is fewer rules, not a longer one.
 
 Two consequences worth knowing before you mark things:
 
-- **Global habits crowd out project decisions.** A rule that has been recalled
-  in other folders outranks a project rule written yesterday that nobody has
-  reached for. If a user's own working preferences fill all eight slots, a new
-  a rule written for the folder they are in may never be shown. Keep the
-  standing set small.
-- **A retired rule stops being shown.** `memgineering retire <ref>` is the way
-  out when a decision no longer holds — it stays visible in recall, ranked last
-  and labelled, but it stops binding.
+- **Global habits used to crowd out project decisions**, and the two budgets
+  are why they no longer can: a rule scoped to the project has its own room and
+  cannot lose every slot to whatever the user has been reaching for lately. It
+  still pays to keep the standing set small — ten is what a session reads.
+- **Three ways out, and they are not the same.** `memgineering revise <ref>
+--no-rule --reason "…"` says it was never a rule: it stops being shown before
+  an edit, and stays a perfectly ordinary current memory that recall returns.
+  `memgineering retire <ref>` says it no longer holds: it stops binding AND
+  drops to the bottom of recall, labelled. `memgineering expire <ref> --until
+<date>` says it held until then: it KEEPS binding and recall keeps returning
+  it, ranked below what is current and labelled from that date. Reach for the
+  first when the marking was the mistake, the second when the decision has been
+  overtaken, and the third when it was always going to run out.
+- **`memgineering rescope <ref>` changes WHERE a rule binds, not whether it
+  does.** `--scope <project>` binds it in that project alone — agents working
+  anywhere else stop being shown it. `--global` binds it everywhere, which is
+  the change hardest to notice afterwards, so it has a flag of its own rather
+  than being what happens when you leave the scope off. Nothing the note says
+  changes either way, and `memgineering undo` reverses it.
+  Ask before widening: a rule the user wrote about one repository, made global,
+  arrives in every session they open.
+- **`--no-rule` on its own asks for nothing else.** No claim, no summary — the
+  conclusion, the summary and the title come back byte for byte, which is the
+  whole reason it exists. It used to go through `revise`, which requires a
+  claim, so taking a marking back meant restating a conclusion nobody had
+  changed, from text this CLI hands back truncated. Do not restate anything;
+  `memgineering undo` reverses it.

package/assets/memgineering-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memgineering-setup
-description: Use when installing or configuring memgineering, when moving a brain between a machine and an account, when renaming or deleting a hosted brain, or whenever the user asks WHICH of their AI tools can see this memory. Triggers include "set up memgineering", "connect my notes", "rename my brain", "delete that brain", "does my other AI see this too", "which of my tools can read this", "will it work in the app on my phone", "no brain is linked".
+description: Use when installing or configuring memgineering, when moving a brain between a machine and an account, when renaming or deleting a hosted brain, or whenever the user asks WHICH of their AI tools can see this memory. Triggers include "set up memgineering", "connect my notes", "rename my brain", "delete that brain", "does my other AI see this too", "which of my tools can read this", "will it work in the app on my phone", "can I use this in ChatGPT", "does it work in Claude.ai", "no brain is linked".
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
@@ -12,20 +12,37 @@ allowed-tools: Bash(memgineering:*)
 Answer this from here, not from a guess. The line is capability, not brand, so
 it does not move as products come and go:
 
-|                                           |                                                                                                               |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| **Any tool that can run a shell command** | Reads and writes the same brain. Nothing has to be built for a tool that does not exist yet.                  |
-| **Any tool that cannot**                  | **Not yet.** There is no connector. A hosted brain is reachable in principle and is not wired up in practice. |
+|                                                            |                                                                                                                                                                                         |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Any tool that can run a shell command**                  | Reads and writes the same brain. Nothing has to be built for a tool that does not exist yet.                                                                                            |
+| **A chat app that takes a custom MCP connector, no shell** | Reads and writes the **hosted** brain on their account through `https://mcp.memgineering.com/mcp`, once they add that connector in the app and sign in with Google. Not a folder brain. |
+| **Neither**                                                | **Not yet.**                                                                                                                                                                            |
 
 `memgineering setup` writes its guidance into the agent tools it finds on the
 machine, and `setup --dry-run` names the ones it actually found rather than
 guessing from a list.
 
 So when someone names a tool and asks whether it remembers too, work it out from
-that line and answer **not yet, and here is what does** — not a hedge, not a
-promise. "You are signed in, so it works everywhere" is the specific wrong
-answer: the account syncs the brain between machines, it does not add a surface
-that can read it.
+those rows and answer plainly — not a hedge, not a promise:
+
+- **ChatGPT** — Settings → **Developer mode** → add an MCP server with
+  `https://mcp.memgineering.com/mcp`, then sign in with Google when it asks.
+- **Claude.ai, Claude Desktop, Cowork** — **Customize** → **Connectors** →
+  **Add custom connector** → the same URL. One connector covers all three, and
+  custom connectors are on every plan, the free one included.
+- It reaches the brain **on their account**. A brain that lives only as a folder
+  on this machine is out of its reach until it is moved up (see "Moving a brain
+  between this machine and their account").
+- Moving it up does NOT make it appear in the chat app by itself. When their
+  brain is still a folder, the answer is both steps, in order: move it up, then
+  add the connector above in their app. An answer that stops at the first step
+  leaves them with an account brain and no way in.
+- `npx memgineering-mcp` — the local, stdio server — is **registry-only**. It has
+  no memory tools; for memory from a chat app, the URL above is the way.
+
+"You are signed in here, so it works everywhere" is still the wrong answer: the
+account syncs the brain between machines, and each chat app needs the connector
+added in that app, once.
 
 ## 1. Register with the agents
 
@@ -49,6 +66,17 @@ Three things to do after running it:
    picks it up on its own when they do. There is nothing to poll and nothing
    to wait for.
 
+The link is the key to that screen, not the code: whoever holds the whole link
+can drive it. Give it only to them, never paste it anywhere else — with
+`--json`, `setup_url` is printed only when no browser opened.
+
+If they chose to upload existing notes on the screen, this machine does NOT
+upload them on its own: the next `memgineering` command shows which folder and
+which account would receive them, with the `push` that sends them. Check with
+them that the account is theirs before running it. And a machine already
+signed in to a different account is never switched by `setup --web` — the
+terminal says so; `logout` first if they really mean to switch.
+
 The screen asks everything `--agent` takes from flags — sign in, where the
 memory lives, which brain, which tools, auto-update, the session hook — with
 the recommended answer pre-selected. A person who is already signed in to
@@ -93,8 +121,16 @@ restart. (Measured: a fresh agent relayed "restart required" as fact, the user
 checked, and it was not one.)
 
 **Ask before setting policy for them.** Auto-update means the tool updates
-itself; `--hook on` means note summaries and their standing rules reach an agent
-unasked. Recommend both, but they are theirs to decide.
+itself: once a day, when a newer version exists, a global install starts
+`memgineering update` in the background and the next run uses it (a project-local
+or npx copy is never touched — it only gets the notice; nor is anything installed
+from a session hook or under CI). One install runs at a time: `memgineering
+update` run while a background install is going answers `update_in_progress`
+and installs nothing — wait a few minutes and run it again; it reports whether
+that install worked. `update_claim_stuck` means a crashed install's leftover
+could not be cleared; its hint names the folder to delete. `--hook on` means note
+summaries and their standing rules reach an agent unasked. Recommend both, but
+they are theirs to decide.
 
 **Error telemetry is theirs to decide too, and defaults to off.** With
 `--error-telemetry on`, the CLI sends an anonymous report when it ITSELF
@@ -146,6 +182,15 @@ answered, and the trust is recorded per hook CONTENT
 so an upgrade that changes a hook asks again. Somebody who is not told this
 reads the silence as an install that did not take.
 
+**An update brings the hooks along.** The first `resurface` (session start)
+after an update — or the next command anybody types — replaces memgineering's
+own hook commands with the new version's, in both Claude Code and Codex, and
+says so once. It replaces only a command memgineering itself shipped: a hook
+someone edited (an absolute path, say), a removed hook, a symlinked or
+unreadable settings file are left exactly as they are, and the last two are
+named once. When a Codex hook changed this way, Codex asks for the review
+above again at its next start — relay that, with the key.
+
 Grok is the case worth knowing, because the obvious guess is wrong: it has
 hooks, more events than either of those two, and `~/.grok/hooks/` needs no
 trust prompt — but a hook there cannot say anything to the model. Measured
@@ -441,9 +486,12 @@ as a next step rather than running it.
 
 ### What a hosted brain does that a folder does not
 
-Every verb works on either kind now, consolidation included. Two things are
+Every verb works on either kind now, consolidation included. Three things are
 only true of a hosted brain.
 
+**A chat app with no shell can reach it** — through the connector at the top of
+this file. A folder brain is reached only by tools that can run `memgineering`.
+
 **Meaning is searched, if a model is configured for it.** That is what lets an
 English question reach a Korean note. It needs `BRAIN_EMBEDDING_URL` and
 `BRAIN_EMBEDDING_MODEL` set on the server; with neither, the brain searches text
@@ -475,7 +523,7 @@ answers without changing its name and the index has to be laid down again.
 ## Turning things off
 
 ```
-memgineering setup --agent --auto-update off
+memgineering setup --agent --auto-update off   # the hook stays as this machine recorded it
 memgineering unlink            # stop reading a brain; notes untouched
 memgineering unlink --purge    # also delete the local index and undo snapshots
 ```