memgineering 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -11,6 +11,673 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-08-16
+
+### Added
+
+- **A memory can say it binds.** `memgineering remember "<the decision>" --rule`
+  marks something as a decision rather than a fact — a colour you will not use, a
+  step never to skip. `memgineering rules` lists what is marked. Ordinary
+  observations are untouched, and a note that never mentions this is stored
+  exactly as before.
+
+- **Your rules turn up before an edit, not after somebody asks.** With the hooks
+  installed (`memgineering setup`, Claude Code and Codex), whichever agent is
+  working in a folder is handed your marked decisions the first time it goes near
+  a file in that session — once, capped at eight lines, silent for the rest of the
+  session. It never blocks an edit and never answers whether one is allowed; the
+  worst it can do is stay quiet.
+
+  This exists because the session-start summary alone was measured not to work.
+  Twice, a session was given a recorded decision — "this site uses no blue", hex
+  codes included — at session start, and shipped a blue page; adding a stronger
+  instruction to that opening made the next run worse. A decision has to arrive
+  when it is about to be broken.
+
+- **`memgineering undo` works on a hosted brain for more than `remember`.** A
+  `revise`, `retire` or `unretire` made against a hosted brain could not be taken
+  back — the refusal said the reverse patch was "not written yet", which was true
+  of nothing: it had been recorded all along and nothing read it. A change to a
+  memory that cannot be reversed is the one thing this tool promises never to
+  make, and it was making it. The reversal is byte for byte, refuses if the note
+  has been written since, and will not run twice.
+
+- **Rules work on a hosted brain.** `memgineering rules` lists them and
+  `remember --rule` creates them there; both used to answer "a hosted brain does
+  not store the marking yet", which was true of the schema and false of the note —
+  a hosted brain keeps the whole text, so the marking arrived with every push and
+  nothing read it. Pushing a brain holding five standing decisions produced a
+  rules list of zero. Rules already pushed are backfilled, so they appear without
+  anyone re-writing them.
+
+  The before-edit hook still reads a brain on this machine: a network call on the
+  path of every file write is not a trade worth making. On a machine pointed at a
+  hosted brain, `memgineering rules --local` is what the hook will actually
+  deliver.
+
+- **A memory can become a rule after it was written**, on a brain in a folder or
+  a hosted one. `memgineering revise <ref> --rule` marks an existing memory as a
+  decision that binds, and `--no-rule` stops it being one; leaving both off
+  changes nothing, as before. Until now the marking was fixed at the moment a note
+  was created, which is the wrong moment — a conclusion usually becomes a rule
+  later, when it changes.
+
+  The hosted half briefly shipped as the worst version of this: the command took
+  the flag, sent nothing, and reported success, so a rule somebody had just turned
+  off was still a rule and nothing said so. It carries now.
+
+- **`memgineering use --json` says where the next write goes.** `destination` is
+  `"hosted"`, `"local"`, or `"pending"` — the third meaning a sign-in is waiting
+  to be approved, so writes land in `brain` until then and in `hosted` after
+  (`destination_until_approved` names the first half). `hosted.sign_in_pending`
+  carries the same distinction as a boolean. `hosted.signed_in` alone cannot
+  answer the question: it is false for both the logged-out and the waiting
+  state, and those land in different places.
+
+- **`memgineering log --json` carries `superseded` on every operation**, on a
+  brain in a folder and a hosted one alike. It is what the printed line uses to
+  decide whether to offer `undo`, and a caller reading the structured output had
+  no way to reach the same conclusion.
+
+### Changed
+
+- **A large push is no longer stopped by the server's rate limit.** The server
+  allows 300 requests a minute and `push` sends one per note, in order, so a brain
+  past that size climbed to the ceiling and stopped part-way — some notes across,
+  some not. A refusal is now waited out and the note re-sent, up to a bounded
+  number of times, and the pause says why once rather than going quiet. Only
+  `429` is retried: it means the request was refused, so nothing was written and
+  repeating it cannot double anything.
+
+- **A hook can no longer hold your session open.** Both callbacks now give up
+  after five seconds and print nothing, and the hook `setup` installs carries a
+  timeout for the host to enforce as well. Neither existed before, and the gap was
+  not theoretical: a brain kept in a folder the OS syncs to the cloud, whose notes
+  had been evicted and would not come back, blocked `resurface` for over two
+  minutes — at the start of every session, because that is when it runs. Run by
+  hand, `resurface` still waits as long as your brain takes; you asked for it and
+  you are watching.
+
+- **`memgineering setup --agent --hook off` now removes the callbacks.** It used
+  to skip installing them, which is right on a machine that never had them and
+  wrong on every machine that did — so the hooks stayed armed under a report that
+  had just printed "Turn it back off with `--hook off`". Only the groups
+  memgineering wrote are taken out; every other hook and setting in that file is
+  left exactly as it was, and a settings file that cannot be parsed is reported
+  rather than passed over in silence.
+
+- **A guide whose markers were deleted no longer duplicates in silence.** Without
+  `<!-- memgineering-start -->` and `<!-- memgineering-end -->` the file read as
+  "never installed", so a second copy of the whole guide was appended — into every
+  session, permanently, with nothing to detect it.
+
+  Where setup can prove it wrote that file, it now skips it, names it, finishes
+  the rest of the run, and exits non-zero. Where it cannot — an install from a
+  release before this one, or a machine whose config is gone — it installs anyway,
+  because refusing there would make a first install impossible for anyone whose
+  own notes happen to use the same two verbs, and says so: "Appended below an
+  unmarked guide", with what to check. Losing only the end marker still repairs
+  itself.
+
+- **Replacing something you edited is said out loud.** setup owns the guide block
+  and the skill files, so an upgrade overwrites them; it now records what it wrote
+  and tells you when what it replaced was not that. Ordinary upgrades stay quiet.
+
+- **A flag that does not exist now says what does.** An unknown option used to
+  answer with one line and nothing to act on, and the recovery — opening the help
+  page — costs ten times what the answer does. The error now lists the command's
+  flags inline, and near-misses get a "did you mean" as well.
+
+- **Codex gets both callbacks too.** `memgineering setup --hook on` now writes
+  them to `~/.codex/hooks.json` as well as Claude Code's settings, with a matcher
+  naming the tools Codex actually reports (`apply_patch` and `Bash` — it has no
+  Read or Grep tool, so its reading is a shell call). Codex was previously listed
+  as unable to run either one; a live session showed otherwise, including that
+  the before-edit hook's context reaches the model. One difference worth knowing:
+  Codex asks you to review new hooks once, at the start of the next session, and
+  runs nothing until you answer — the setup report now says so.
+
+- **Grok is a supported tool.** `memgineering setup` installs the guide into
+  `~/.grok/rules/memgineering.md` and the skills into `~/.grok/skills/`, and Grok
+  loads both on its own.
+
+  Your rules reach it at the end of a turn rather than before an edit, and that
+  is the most the host allows. Three of Grok's hook events were each tried with a
+  value the session could not otherwise know — `PreToolUse` with
+  `additionalContext`, `SessionStart` stdout, `UserPromptSubmit` with
+  `additionalContext` — and all three hooks ran while none of the three arrived.
+  `Stop` does arrive. So the rules land as the turn finishes: too late for what
+  that turn already wrote, in time for everything after it. It costs one extra
+  round, once a session, because speaking there keeps the agent working.
+  `resurface` gets no hook on Grok at all; the guide asks for it instead.
+
+- **The third tool is called Antigravity now.** Gemini CLI is discontinued and
+  Antigravity CLI took its place, keeping the same home — a line planted in
+  `~/.gemini/GEMINI.md` came back out of an `agy` session word for word, and one
+  planted in `~/.antigravity/` did not. So nothing moves: the guide and the
+  skills install exactly where they did, `--tools gemini` still selects it, and
+  only the name shown to you changes. It still has no hooks, so its skills tell
+  its agent to run `resurface` and `rules` itself.
+
+- `memgineering setup --hook on` now arms two callbacks instead of one, and the
+  report names both. `--hook off` still installs neither.
+
+- `sync-rules` is described as copying the brain's **read/index exclusions**,
+  which is what it has always copied. "Rules" alone now has another owner.
+
+- **The bundled skills are English throughout, including their trigger
+  phrases.** 0.5.0 shipped a handful of Korean phrases in those triggers, so a
+  Korean speaker's agent could match a skill from the words they actually used;
+  everyone else got a package with one arbitrary second language in it. Picking
+  the trigger language at `setup` time is the right answer and is not built yet,
+  so until it is, the phrases are English.
+
+  Measured before saying so: the same Korean request that used to open a skill
+  still opens it with only English phrases installed, and six Korean requests
+  across two shapes were all handled correctly. A description is read by a model
+  that knows the language either way — the phrases name the situation, not the
+  wording. Asking for your memory in Korean still works.
+
+- **The guidance now says a fact has to be checked, not worked out.** A session
+  that reads an address, an identifier or a version and then reasons its way to a
+  different one can write that reasoning into the brain as fact, where every later
+  session recalls it as one. A guess in a file turns up in a diff; a guess in a
+  memory does not. Two sentences, in the hub and in `memgineering-writing`: a
+  decision is whatever the user says it is, and anything a command or a file could
+  confirm goes in verified or not at all.
+
+- **Tools that nothing calls for them now get told so.** On Antigravity — which
+  loads no skills of its own, measured — the installed guide was a router
+  pointing at five skills that were never opened, so a brain full of answers went
+  unread across a whole session. `setup` now appends two lines to the guide it
+  writes for any tool with no session hook: run `memgineering resurface` when you
+  start work in a folder, and `memgineering rules` before changing a file. Tools
+  that do get called back are unchanged, and see nothing extra.
+
+  Measured on the same task before and after: no memory calls and a generic
+  answer, then `resurface` + `rules`, the right answer, and the decision recorded
+  as a rule without being asked.
+
+### Fixed
+
+- **Everything on the install screen is drawn by the same hand.** The
+  comparison's row rules were 1px hairlines running directly underneath
+  hand-drawn frames — the only straight edges on the page, and the first thing
+  the eye found. Rules, the recommended badge and the checkboxes are drawn now,
+  and hovering a drawn control makes its outline quiver in place the way the
+  site's do, instead of repainting a background the way nothing else in the
+  product does. Reduced-motion settings hold it to a single frame.
+
+- **The first install screen stops asking you to match a table to a pair of
+  cards.** It compared "this machine only" against "in an account" in a table,
+  and then offered the choice underneath as two cards — in the opposite order to
+  the columns, worded differently from the column headers. Someone seeing it for
+  the first time could not tell which card the left column was about, which is
+  the one thing that screen exists to make obvious. The two answers are now the
+  table's own column headers: picking one paints its whole column, so every row
+  is read against the answer it belongs to. The recommended one is first in both
+  senses, because there is only one order left to be first in.
+
+- **The Korean install screen is written the way the rest of it should have
+  been.** Every sentence moved to 해요체 and lost the clauses it did not need —
+  the register a person deciding something is spoken to, rather than one being
+  informed of a decision. The draft terms moved with it; a policy nobody can read
+  is not a stricter policy.
+
+- **A rule about a command now actually arrives.** The before-edit hook is
+  installed with a tool matcher, and `Bash` was not in it — so a decision about
+  committing, deleting or deploying could never be shown, because those are shell
+  calls. A fresh agent asked to make "never put emoji in commit messages" stick
+  ran its whole task through `Bash` and was handed that rule zero times. The
+  matcher already carried `Read`, `Glob` and `Grep`, none of which writes
+  anything, so waiting for a "file tool" was never waiting for a write.
+  **Re-run `memgineering setup` to pick this up** — the matcher lives in your
+  tool's settings and an upgrade alone does not rewrite it.
+
+- **Renaming your notes folder no longer makes your rules disappear.** When the
+  brain you set as default is not on disk, everything falls through to the one
+  that is — deliberate, so an unmounted drive does not stop you working. Nothing
+  said it had happened, so `rules` answered from the other brain with "no
+  standing decisions recorded", which reads as "I never wrote any down" and gets
+  acted on by writing them again, into a brain that is not the one you lost.
+  `use` said "because it is the only brain linked" while two were linked.
+  `rules`, `use` and `resurface` now name the folder they could not reach, say
+  the answer came from somewhere else, say nothing is lost, and give the one
+  command that fixes it. Silent when your default is fine.
+
+- **The sign-in screens are on memgineering.com.** Approving a sign-in used to
+  happen on `api.memgineering.com`, an API subdomain, on a page built from
+  colours that matched nothing else in the product. Approval, the refusals and
+  the "you're done" screen are now all at `memgineering.com/auth/device`, drawn
+  from the same stylesheet as the rest of the site. Nothing changes in the CLI —
+  `login` opens whichever address the server hands it.
+
+- **The install screen draws itself again.** `memgineering setup --web` serves one
+  self-contained page under `default-src 'none'`, and that policy named no
+  `img-src` and no `font-src` — so the browser silently dropped every asset the
+  page was carrying inside itself. The hand-drawn borders around the cards, the
+  inputs and the buttons never painted, and neither did the typeface. On the
+  account step this cost the reader the way forward: the `Next` button is drawn
+  rather than filled with a colour, so it rendered as an invisible rectangle with
+  a label the same shade as the page. The policy now permits `data:` for images
+  and fonts, and nothing else — no host, no scheme, no wildcard — so the screen
+  still opens with the machine offline. A test now reads the page for the
+  schemes it actually uses and asks the policy about each one, which is the
+  comparison nobody was making: both files were correct about themselves.
+
+- **A hosted brain shows why a memory changed, in the output you get without
+  asking.** Every write is told to carry a `--reason`, on the argument that it is
+  the only part of the record still worth anything six months later — and then
+  neither read command printed one. On a hosted brain, `memgineering evidence`
+  answered with `surfaced 8 · opened 4` and stopped, and `memgineering log` gave a
+  timestamp and a path. The reasons had been in the response all along, and in
+  `--json`, so nothing was lost; it was simply never shown, which for a default
+  output is the same thing.
+
+  Both commands now print the same report from a hosted brain that they print
+  from one on your disk: the title, the standing and what it means, the ledger,
+  and the reason quoted. `log` additionally shows who made each change, whether
+  it was already undone, and whether the note has moved on since — all of which
+  the server was sending and the client was discarding.
+
+- **`memgineering use` named the wrong brain.** Signed in and pointed at a
+  hosted brain, it reported the folder on this disk — a real folder, that
+  nothing had written to in weeks — while every `recall` and `remember` went to
+  the server. Naming the wrong destination is the one thing this tool cannot do:
+  nothing about the answer looks wrong until somebody goes looking for a note
+  that was never written there.
+
+  It now answers with whichever brain the next command will actually use, in all
+  three states: the hosted one when signed in; the folder when the pointer is
+  there but the sign-in is not, because that is where writes land; and, when a
+  sign-in is merely waiting to be approved, both — the folder until somebody
+  approves it, the hosted brain after. It reads state off the disk, so it
+  answers with the server down and it never completes a sign-in as a side
+  effect of being asked a question. See the `--json` fields under Added.
+
+- **`memgineering pull` uses the brain this machine is pointed at.** It was the
+  only hosted verb that could not answer "which brain" from state every other
+  verb reads, so on an account with two, the command somebody runs to back up
+  the brain they had been using all session answered "more than one hosted brain
+  — say which". `--brain` still wins, an unpointed machine with two brains still
+  gets the refusal, and the success line now names the brain it downloaded.
+
+- **`memgineering pull` says which of your brains the folder does not contain.**
+  A tester pulled, was told 21 notes had arrived, and had no reason to doubt it —
+  the other 45 of their 66 were in a second hosted brain on the same account, and
+  a successful run never mentioned that it existed. A backup nobody knows is
+  partial is worse than one that failed. Both the real run and `--dry-run` now
+  name the other brains and give a command that fetches one; `--json` carries
+  `other_brains` and a hint saying not to call this a backup until each has been
+  pulled.
+
+- **Asking where an install stands no longer means running the command that
+  installs.** There is no `status` verb, and the answer lives behind
+  `memgineering setup --agent --dry-run`, which writes nothing. A tester looking
+  for it either avoided `setup` — whose name says it installs — and got no
+  answer, or ran it and changed something to find out. `--help` now names the
+  dry run on the `setup` line, and the setup skill collects the three read-only
+  questions (`setup --dry-run`, `whoami`, `use`) in one place. It also names
+  `memgineering guard` as the hook's entry point, which stays out of `--help` on
+  purpose: it reads a hook payload on stdin and does nothing without one.
+
+- **A question asked as a sentence is told what `recall` actually matched.**
+  "Only titles, aliases and summaries are searched" printed on zero results only
+  — the one case where there is nothing to misread. Asked as a whole sentence,
+  recall can return notes that share a single ordinary word with the question,
+  and every card reads `stated` with nothing to say the match was on "not"
+  rather than on the subject. That sentence now also appears under the results
+  when the query is a question or four words or more. It is not a warning: this
+  cannot know whether the results are any good, and a ⚠ over a right answer is
+  how a reader learns to skip the line.
+
+- **A hosted card with no age no longer reads `NaN years ago`.** The guard
+  tested for `null` and a server that omits the field sends `undefined`, so a
+  real answer arrived wearing a number that was not one.
+
+- **`memgineering recall` says which results are decisions you already made.**
+  `resurface` has labelled them "a standing decision" since rules existed, and
+  `recall` — the verb an agent reaches for far more often — returned a decision
+  and an ordinary observation looking identical. A brain with five standing
+  decisions in it could answer a question without saying which of the answers
+  the user had already committed to. The card now says so, and `--json` carries
+  a `binding` field on every card: present and `false` on an ordinary memory, so
+  a caller can tell "not a rule" from "this version does not say".
+
+  A hosted brain shows this once its server is updated; nothing breaks in the
+  meantime, the label is simply absent.
+
+- **An id from `memgineering log` no longer looks like one from `recall`.** They
+  are the same length in the same alphabet, arrive in the same backticks, and
+  nothing said which was which — so an agent read an operation id off `log`, ran
+  `open` on it, and was told "nothing here matches — try searching". No search
+  can return an operation id. `log` now labels each one `undo:`, and `op:`
+  wherever `undo` would refuse it: an operation already undone, one that is
+  itself an undo, one whose note has been written since, or a verb that brain
+  cannot reverse — a hosted brain cannot reverse an `exclude`, and neither side
+  reverses an `import`. Fed one anyway, `open` says what the id is, which change
+  it names, the note it touched, and how to read that note; a truncated id works
+  there too, since `undo` accepts one.
+
+- **`memgineering log` no longer warns that notes changed when they did not.**
+  It checked each operation's file through the note reader, which refuses
+  excluded and deny-listed paths — and read that refusal as "the file is gone".
+  So every `exclude` anybody ran was reported as changed (its target is
+  `.memgignore`, which is deny-listed), and so was the entire history of any
+  note that had been excluded. Separately, the divergence check was handed the
+  rows newest-first while it keeps the last one it sees per note, so it compared
+  against the OLDEST operation — an ordinary remember-then-revise reported the
+  note as edited outside the tool, about the tool's own write. Measured in each
+  case: the warning appeared and `undo` reversed the operation happily.
+
+- **A crafted name from a hosted brain can no longer rewrite your terminal.**
+  Titles, paths, handles, brain names, account names, ranking reasons and server
+  hints were printed as they arrived, so a string containing terminal escape
+  sequences could erase the lines above it, move the cursor, or plant a
+  clickable link that goes somewhere else. `pull` was worse than a rendering
+  bug: with no destination given it names the folder after the brain, so a
+  crafted name created a directory on your disk carrying those bytes.
+
+  Every command that renders one of these strings now strips it — `recall`
+  (cards and the contradictions block), `open`, `evidence`, `log`, `resurface`,
+  `rules`, `remember`, `revise`, `undo`, `retire`, `unretire`, `exclude`,
+  `unexclude`, `use`, `whoami`, `push`, `pull`, `login`, `setup`'s sign-in step,
+  `update`, `link`'s previews, and the error output. Handles are stripped where
+  they are built rather than where they are printed, because a handle this tool
+  did not mint is the note's own `id:` field and there are a dozen places that
+  print one.
+
+  A brain in a folder gets the same treatment, and it took three passes to mean
+  it. The first sweep drove only each verb's hosted half, so a local note's
+  title, path, claim, scope, headings and ledger target still reached the
+  terminal. Patching those by hand missed five more, and the round after that
+  missed six — which is what finally replaced "check each one" with mutation
+  testing: break one strip, and a suite has to go red. `stripControl` says why
+  this is in scope at all — a folder brain can have synced from another machine
+  or be written by a team — and a note that arrived over Dropbox is as much
+  somebody else's writing as one that arrived over HTTPS.
+
+  Two suites drive it, one per brain, against notes and responses poisoned at
+  both ends of every string: eighteen local surfaces and eighteen hosted ones,
+  plus three server replies the fixture previously could not produce — a
+  reversal the server cannot describe, a curation that changed nothing, and a
+  recall carrying a contradiction.
+
+  Coverage is stated as measured rather than asserted. Breaking each of the 120
+  strips one at a time and re-running the suite, 92 are caught by a test. Of the
+  28 that are not, most cannot be: `revise`'s diff renders YAML source, and the
+  serializer has already turned any control character into the four letters
+  `\x1b` before it reaches a screen; `open`'s claim line prints two enums;
+  `.memgignore` refuses a path with control characters before the branch that
+  would echo one; ids and error codes are excluded from the poisoned fixture on
+  purpose, since a caller passes an id back as a selector and branches on a code.
+  What is left genuinely untested is small and named: the browser consent screen,
+  which needs a terminal; the two `login` lines that need a browser to open and a
+  device flow to be approved; and a handful of second arms only a particular
+  server reply produces. Saying "every command is covered" was wrong four
+  releases running, so this says the number instead.
+
+### Agent guidance
+
+- **Re-run `memgineering setup` after upgrading, then restart the
+  conversation.** Two things this release changes live outside the package: the
+  guidance block in your tool's instructions file, and the before-edit hook's
+  tool matcher — which gains `Bash`, without which a rule about a command is
+  never shown. Upgrading the CLI rewrites neither; `setup` does. The restart is
+  because the guidance is read once, when a conversation starts.
+
+- **The block memgineering writes into your `CLAUDE.md` is now a third of the
+  size** — 178 lines to 52, and no command syntax at all. That block is in your
+  agent's context for every session forever, and it had grown into a second copy
+  of a manual that already existed as an on-demand skill. What it keeps is what
+  has to be true before any skill loads: what a brain is, which tools this
+  actually reaches, when to reach for it, and where the detail is.
+
+- **Five skills instead of two.** `memgineering-memory` is now the map — which
+  verb answers which question — and points at `memgineering-recall` (recall,
+  open, evidence, resurface), `memgineering-writing` (remember, revise, undo,
+  retire, exclude, filling in `01_BASE/`), `memgineering-rules` (`--rule`, the
+  eight-slot budget, what the before-edit hook shows) and `memgineering-setup`,
+  which gains `push`/`pull`. Nothing was dropped; `resurface` had been explained
+  twice and now is explained once.
+
+- `MEMGINEERING.md` 0.2.0 → 0.4.0, covering `--rule`: what counts as a decision,
+  and that a user saying "from now on" or "never" is making one without using
+  the word. **Restart your agent session after upgrading** so the new guidance
+  is read.
+
+## [0.5.0] — 2026-08-12
+
+### Added
+
+- **Every command works on a hosted brain.** `revise`, `resurface`, `retire`,
+  `unretire`, `exclude` and `unexclude` used to refuse when this machine was
+  pointed at a hosted brain and tell you to add `--local`. They go to the server
+  now. Nothing memgineering offers says no because your brain is not on this
+  disk.
+
+- **The setup screen starts with where your memory goes.**
+  `memgineering setup --web` used to open a Google sign-in before it showed you
+  anything, so the first thing you saw was a consent page for a product that
+  had not told you what it was. It now opens on the choice — what memgineering is in one
+  sentence, then a plain comparison of keeping the memory on this machine
+  against keeping it in an account, and what each costs. One brain is free, and
+  stays free. The sign-in only starts once you have picked it, and the code to
+  approve is shown on the last screen. Draft terms and a privacy draft are
+  reachable from the same screen; they are marked as drafts because they have
+  not been through legal review.
+
+- **`memgineering pull [folder]`** — download your hosted brain back to this
+  machine, as the markdown it is. Until now notes went up and nothing came back,
+  so "your memory is yours" stopped being demonstrable the moment you used the
+  hosted side. It **never overwrites**: a file already at that path is left
+  exactly as it is and reported as skipped, which is what makes it safe to point
+  at the wrong folder and what makes an interrupted download finishable by
+  running the command again. Notes your rules exclude come down too — excluded
+  means "stop reading this", not "this is no longer yours" — and `.memgignore`
+  travels with them, so the folder does not silently un-exclude anything. The
+  result is plain markdown; `memgineering link <folder>` is what turns it into a
+  brain on this machine, and it is not done for you. `--dry-run` lists what would
+  be written without writing it.
+
+- **`memgineering push`** — upload the brain on this machine to your hosted one,
+  keeping every note at the path it already had. Nothing is deleted locally, a
+  note already up there is counted as already up there rather than as a failure
+  (so an interrupted upload is finished by running the command again), and any
+  note the server refuses is listed in the summary instead of quietly dropped
+  from the count. `--dry-run` lists what would go without sending anything.
+
+### Changed
+
+- **Setup no longer decides about accounts behind your back.** Run by an agent,
+  it skipped sign-in and said nothing — so you got a folder on one machine and
+  found out later that your memory does not follow you. It now says plainly that
+  no account was used and how to connect one, and the install tells your agent to
+  ask you first: memory on this machine, or synced across your devices and tools.
+
+- **After install, your agent finishes the job.** Installing used to print
+  `Next: memgineering setup` — which agents dutifully relayed to their user as a
+  command to type, in a product whose whole premise is that the agent does this
+  for you. The install now tells the agent to ask you one question — should it
+  set things up, or would you rather choose on a screen — and then run setup
+  itself. The message is also no longer suppressed when output is piped, which
+  is exactly the case where an agent is the one reading it.
+
+- **`--local` still does exactly what it did.** The product works with no
+  server: pass `--local` to any command and it reads and writes the folder on
+  this machine, whether or not you are signed in.
+
+- **A hosted `resurface` says what it ranked by.** It has three signals where a
+  local brain has four — it cannot know which folder you asked from, because the
+  server records what was recalled and never where you were standing. The output
+  names the signals it used rather than leaving you to notice that "recalled 14×
+  in this folder" stopped appearing.
+
+- **`revise --input` is refused against a hosted brain**, rather than partly
+  honoured. The JSON can name a different memory and set fields the flags do not
+  expose, so sending only the understood parts would report a success for a
+  change you did not ask for. Pass the change as flags, or use `--local`.
+
+- **What you exclude travels with your brain.** The rules live in a
+  `.memgignore` file inside the brain rather than in a setting beside it, so a
+  hosted brain pulled back down to a folder is still scoped the way you scoped
+  it. `undo` for an exclusion is `unexclude`, not `undo <op_id>`.
+
+- **`memgineering login`, `logout` and `whoami`** — sign in to a hosted brain.
+  Optional, and nothing that already worked needs it: a brain is still a folder
+  of markdown files on your machine, and every other command works on it with no
+  account and no network.
+
+  `login` pairs this machine with an account without a token ever appearing in a
+  browser. It prints a code, opens an approval page, and collects the token
+  itself once you approve — so the credential never lands on a screen, in a
+  scrollback, or in a chat window.
+
+  **Agents should use `login --emit-only`.** It starts the sign-in, opens the
+  browser and returns immediately rather than waiting for a human to click,
+  which no agent's command timeout survives. The next `memgineering` command
+  claims the token automatically. Show the printed code in your reply: the
+  approval page asks the user to check it against what they were shown, and on
+  surfaces where you are the only thing that saw it, they cannot.
+
+  `logout` revokes on the server before forgetting anything locally — a token
+  deleted only here still works for whoever has a copy. `--all` ends every
+  session on the account, `--local` forgets it here when the server is
+  unreachable and says plainly what that does not do.
+
+- **`setup` offers an account as its first step, and lets you walk past it.**
+  Skipping installs byte-for-byte the same files; there is a test that compares
+  the two trees. With no terminal it does nothing unless you pass `--login`, so
+  an agent running `setup --agent` never opens a browser you did not ask for.
+
+- **`MEMGINEERING_API_URL`** points the account commands at a different brain
+  server. The token is stored with the server that minted it and is never sent
+  anywhere else.
+
+- **The `--human` prompt no longer hangs where there is no terminal.** Asking for
+  `--human` says which mode you want; it does not conjure a screen to draw a
+  prompt on.
+
+- **The setup screen no longer promises a sync it does not perform.** Its first
+  screen ticks "the same memory on another machine" for keeping the memory in an
+  account — and choosing that only signed you in. No hosted brain was created and
+  no note was uploaded, so you would have found out on the second machine. The
+  last screen now says the notes are still only on this machine and what changes
+  that; the machine-readable half tells your agent the same thing, and to ask you
+  before sending anything to a server.
+
+- **Two screens no longer ask near-identical questions.** "기억을 어디에
+  둘까요?" (this machine or an account) was followed two screens later by "기억을
+  어디에 담을까요?" (which folder to read). The second is now "어느 폴더를
+  쓸까요?".
+
+- **The screen separates what is kept here from what an upload sends.** It said
+  only a note's title and first paragraph get stored — true of the index on this
+  machine, and read as the whole of what reaches the server by anyone who had
+  just chosen an account. Uploading sends the entire file, and the screen now
+  says so where the claim is made.
+
+- **The privacy draft says notes are stored in plain text.** No end-to-end
+  encryption; whoever runs the server can technically read them, and not doing so
+  is a promise rather than an impossibility. It was the one fact a person
+  weighing whether to put a diary in an account most needs, and the easiest to
+  leave out.
+
+- **The setup screen stopped handing out commands.** It answered three of a
+  non-developer's questions with one — how to stop a note being surfaced, how to
+  update, how to connect a folder — and each answer was a command to type, on the
+  one screen built for somebody who has never opened a terminal. Each is now
+  phrased as something to ask their agent for. A test fails if any
+  `memgineering <verb>` reappears on that page.
+
+- **Folder suggestions say how many notes each one holds.** The list offered
+  every folder containing at least one markdown file, so a photo archive with a
+  stray README sat beside somebody's actual notes with nothing to tell them
+  apart. The count is the reason each row is there, so it is now on the row.
+  Filtering harder was the wrong fix: a folder with one note is still notes.
+
+- **The terms draft lists what it has not decided.** Legal entity and
+  jurisdiction, where the servers are, how long a deletion takes to reach
+  backups, how a breach would be announced, and where to delete an account —
+  absent from the draft, and now absent in writing rather than by omission.
+
+- **`recall` stopped telling Korean users their own Korean notes were
+  unreachable.** When a query found nothing, the footer could claim "this
+  brain's notes are mostly written in English … no rewording in another
+  language will reach them" — in a brain holding Korean notes. Two scaffolding
+  files were voting: `01_BASE/` was already excluded, `00_HUB/` was not, and on
+  a small brain one English note `init` wrote decides the count. A note like
+  `글꼴은 Pretendard 하나로` then votes English on the strength of the product
+  name, and the majority flips. The hub no longer votes, and the warning is
+  suppressed outright when any note somebody wrote is in the asker's script —
+  the claim is about reachability, and one such note makes it false.
+
+  Caught by a fresh-context agent, which read the footer, believed it, and told
+  its user that Korean titles are not searchable. A hint that is wrong does not
+  merely mislead — it stops the tool being used.
+
+- **`resurface` shows what a brain holds before anything has been recalled from
+  it.** It ranked purely on evidence of use — recalled here, recalled anywhere,
+  read lately — and dropped everything that scored zero. A note that had only
+  ever been written scored zero, so a brain nobody had searched yet returned its
+  five untouched `01_BASE/` templates and none of its actual notes, even at
+  `--limit 8`. That is a loop with no way in: a note is not surfaced until it has
+  been recalled, and surfacing is how you find out it exists.
+
+  It runs at session start, so that was an agent's entire first impression of the
+  brain. Measured: one saw five "not filled in yet" placeholders, concluded there
+  was nothing there, and did not call memgineering again for the rest of the
+  session.
+
+  Never-reached notes now rank, below anything with evidence behind them, and
+  untouched templates take at most two of the slots instead of all five. When
+  nothing has been recalled yet the page says so in a line — the order means
+  "what this holds", not "what matters here". Refusing to guess was right;
+  refusing to speak was not.
+
+- **Checking whether you are signed in no longer opens a Google consent page.**
+  The `not_signed_in` hint read "YOU run `memgineering login --emit-only`" with
+  no precondition attached, and agents follow instructions — so an agent that
+  ran `whoami` to orient itself started a sign-in. Measured during testing:
+  three consent windows appeared in a user's browser in a session where nobody
+  had mentioned accounts. `setup` already refused to do this on the grounds that
+  nobody should be sent to a consent screen they did not ask for; the tool held
+  both positions and this one ran more often. The hint now leads with the fact
+  that an account is optional and `--local` is right there, and gates the
+  sign-in on the user having asked for one.
+
+- **`resurface` says what to do with what it just showed.** It printed five
+  cards and stopped, at session start, to a reader that is always an agent. One
+  was handed a note saying this site does not use blue, with the hex codes in
+  the summary, and shipped a page with a blue accent: the memory reached its
+  context and never reached its output. It now closes with three lines — these
+  are the user's own decisions, follow them unasked, recall before answering
+  something already settled, remember what this session decides. Untouched
+  templates also stop explaining themselves at length when real notes share the
+  page; six lines about unfilled files were burying the two that mattered.
+
+- **A hosted brain answers the same way as a local one when nothing has been
+  recalled from it yet** — the notes, plus a line saying the order is what the
+  brain holds rather than what matters here. It used to return an empty list,
+  which reads as an empty brain.
+
+### Agent guidance
+
+- **The hub now says which tools this actually reaches.** A fresh-context test
+  asked an agent to make ChatGPT, Claude and Codex share one memory; it set up
+  the two it could and then had to read the product's source code to find out
+  whether ChatGPT was possible at all. On a machine without that source it
+  would have had to guess. The guidance now states plainly that `setup` covers
+  Claude Code, Codex and Gemini CLI, that anything with a shell works, and that
+  web and phone surfaces have no connector yet — including the specific wrong
+  answer to avoid ("you are signed in, so it works everywhere").
+
+- The bundled guidance changed: the hub now tells your agent to fetch your
+  notes back with `pull` whenever you ask for them, and the setup skill says
+  the account question on the first screen is yours to answer rather than
+  something it should decide or pre-empt. **Restart your agent session after
+  upgrading** — the guidance is read once, when the session starts.
+
 ## [0.4.2] — 2026-08-10
 
 ### Fixed