memgineering 0.25.1 → 0.25.2

package/CHANGELOG.md

@@ -11,6 +11,62 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [0.25.2] — 2026-10-05
+
+Small fixes found by an independent review of 0.25.0 and 0.25.1. Nothing here
+changes what you type.
+
+### Fixed
+
+- **A refresh `setup` keeps your choices.** `memgineering setup` run again
+  without `--hook` or `--auto-update` used to turn both back on. It now keeps
+  the hook and auto-update choices recorded on this machine, including a hook
+  choice made on the `setup --web` screen. On a machine set
+  up before this release, the hook choice is read from whether the hook is
+  installed. A kept choice is no longer listed as a default nobody was asked
+  about.
+- **A command no longer waits on the update check.** Before a background
+  install, the CLI asks npm, pnpm and bun where they keep global packages. That
+  could hold your command open for up to 15 seconds after its output, and
+  longer behind a version manager. The CLI now asks all three at once and gives
+  up after 1.5 seconds. If it cannot tell how memgineering was installed, it
+  installs nothing and prints the usual "is available — `memgineering update`"
+  line.
+- **The before-edit hook never starts an update**, even when it is called with
+  a flag first (`memgineering --json guard`). The same holds for `resurface`.
+- **Two commands starting together cannot both start a background install.**
+  This could happen when the previous install had been left unfinished. If the
+  lock behind this fix is ever left in place, `memgineering update` says so
+  (`update_claim_stuck`) instead of reporting another install in progress.
+- **Both sides of a conflict appear in recall.** When a note contradicted an
+  unfilled base template, the limit of two template cards could hide one side
+  while recall said "Both sides are above". Both sides now show, even if that
+  means more than two template cards, and the line counting held-back
+  templates says so.
+- **Hosted recall by meaning no longer drops a base note you have filled in.**
+  A `USER.md` or other `01_BASE/` note you rewrote in your own words was
+  treated as an untouched template and left out. Only an exact, untouched
+  template is held back now.
+- **A chat-app connector cannot change a rule by other routes.** Retiring,
+  restoring or undoing a rule from a connector is now refused with
+  `rule_needs_a_person`, as editing one already was. That includes undoing the
+  `remember` that created a rule. A connector's `undo` with no id undoes only
+  that app's own changes, including those made before its sign-in was
+  refreshed. If it has made none, it is told so and nothing is undone.
+- Hosted `retire` and `unretire` no longer say that `undo` cannot reverse
+  them. It can, and their hint now names both ways back.
+- `setup --help` gives ChatGPT its own route: Settings → Developer mode → add
+  an MCP server. Claude.ai, Claude Desktop and Cowork use a custom connector.
+- `setup --web` prints its terminal lines in English.
+
+### Agent guidance
+
+- `memgineering-setup`: turning auto-update off with
+  `setup --agent --auto-update off` no longer needs `--hook`, because the hook
+  stays as this machine recorded it. It also explains `update_claim_stuck`.
+- `memgineering-recall`: a template card that is one side of a conflict comes
+  on top of the two-card limit.
+
 ## [0.25.1] — 2026-10-05
 
 A security release. Upgrade if you use `setup --web`, or a hosted brain with a

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.25.1
+version: 0.25.2
 ---
 
 # memgineering

package/assets/memgineering-recall/SKILL.md

@@ -210,8 +210,9 @@ it, so it is evidence of nothing — do not quote it back as what they think. Wh
 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`. At most two such cards come
-back per answer; the rest are counted (`templates_withheld`), never silently
-dropped, and nothing anyone wrote is ever held back.
+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_,

package/assets/memgineering-setup/SKILL.md

@@ -127,7 +127,8 @@ or npx copy is never touched — it only gets the notice; nor is anything instal
 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. `--hook on` means note
+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.
 
@@ -513,7 +514,7 @@ answers without changing its name and the index has to be laid down again.
 ## Turning things off
 
 ```
-memgineering setup --agent --auto-update off --hook <on|off>   # --agent sets both; keep the hook as it was
+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
 ```

package/dist/index.js

@@ -2441,14 +2441,6 @@ var init_planner = __esm({
   }
 });
 
-// ../../packages/memory-engine/src/recall/semantic.ts
-var init_semantic = __esm({
-  "../../packages/memory-engine/src/recall/semantic.ts"() {
-    "use strict";
-    init_markdown_mapping();
-  }
-});
-
 // ../../packages/memory-engine/src/base-templates.ts
 function base(id, title, summary, body) {
   return [
@@ -2556,6 +2548,14 @@ var init_base_templates = __esm({
   }
 });
 
+// ../../packages/memory-engine/src/recall/semantic.ts
+var init_semantic = __esm({
+  "../../packages/memory-engine/src/recall/semantic.ts"() {
+    "use strict";
+    init_base_templates();
+  }
+});
+
 // ../../packages/memory-engine/src/recall/unfilled.ts
 var UNFILLED_FIELDS;
 var init_unfilled = __esm({
@@ -2577,6 +2577,13 @@ var init_unfilled = __esm({
   }
 });
 
+// ../../packages/memory-engine/src/setup-progress.ts
+var init_setup_progress = __esm({
+  "../../packages/memory-engine/src/setup-progress.ts"() {
+    "use strict";
+  }
+});
+
 // ../../packages/memory-engine/src/recall/query-prefix.ts
 var init_query_prefix = __esm({
   "../../packages/memory-engine/src/recall/query-prefix.ts"() {
@@ -4905,6 +4912,7 @@ var init_src = __esm({
     init_planner();
     init_semantic();
     init_unfilled();
+    init_setup_progress();
     init_query_prefix();
     init_base_templates();
     init_scope_spread();
@@ -5507,6 +5515,13 @@ var init_config = __esm({
          * answer as "older than this CLI" and wants the same one command.
          */
         guidanceVersion: z8.string().optional(),
+        /**
+         * The person's answer to "arm the hooks?", as they gave it — not whether
+         * this machine's tools could take one. A flag-less `setup` reads it back,
+         * so a refresh keeps what they chose instead of setup's default (0.25.2).
+         * Absent on a machine set up before it was recorded.
+         */
+        hook: z8.enum(["on", "off"]).optional().catch(void 0),
         /**
          * Notes `setup --web` was asked to upload, not yet sent.
          *
@@ -7864,13 +7879,208 @@ var init_setup_signin = __esm({
   }
 });
 
+// src/lib/next-step.ts
+import { mkdir as mkdir15, readFile as readFile24, writeFile as writeFile13 } from "fs/promises";
+import { join as join23 } from "path";
+function isSetUp(cfg) {
+  return Object.keys(cfg.system.installed).length > 0;
+}
+function connectedMarker(at) {
+  return join23(brandHome(), `setup-connected-shown-${at.replace(/[^0-9A-Za-z]/g, "")}`);
+}
+async function connectedNoticeShown(at) {
+  return readFile24(connectedMarker(at), "utf8").then(
+    () => true,
+    () => false
+  );
+}
+async function markConnectedNoticeShown(at) {
+  try {
+    await mkdir15(brandHome(), { recursive: true });
+    await writeFile13(connectedMarker(at), `${(/* @__PURE__ */ new Date()).toISOString()}
+`);
+  } catch {
+  }
+}
+async function claimFullSetupNotice() {
+  const marker = join23(brandHome(), "setup-notice-shown");
+  try {
+    await readFile24(marker, "utf8");
+    return false;
+  } catch {
+  }
+  try {
+    await mkdir15(brandHome(), { recursive: true });
+    await writeFile13(marker, `${(/* @__PURE__ */ new Date()).toISOString()}
+`);
+  } catch {
+  }
+  return true;
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function confirmUploadNotice(p) {
+  const who = p.account_email ?? "the account `setup --web` connected";
+  const brain = p.brain_id && UUID.test(p.brain_id) ? ` --brain ${p.brain_id}` : "";
+  return `## Notes are waiting to be uploaded \u2014 after a check.
+
+\`memgineering setup --web\` chose to upload \`${p.path}\` to a brain on **${who}**.
+This machine has not sent them: an upload decided on the setup screen waits
+until somebody here has seen which account would receive the notes.
+
+If that is your user's account, this uploads them:
+
+\`\`\`bash
+memgineering push --vault ${shellQuote(p.path)}${brain}
+\`\`\`
+
+If it is not, \`memgineering logout\` disconnects this machine from that account
+and nothing is uploaded. If you are not sure which it is, ask them.`;
+}
+function setupConnectedNotice(c2) {
+  const who = c2.email ?? "an account with no email on record";
+  return `## This machine is signed in as **${who}**.
+
+\`memgineering setup --web\` connected it to that account. If that is not your user's account,
+\`memgineering logout\` disconnects it, and nothing they write reaches that brain.`;
+}
+function nextStepFor(cfg, signedIn = false, seen = {}) {
+  if (cfg.system.pendingUpload) {
+    return { id: "confirm_upload", markdown: confirmUploadNotice(cfg.system.pendingUpload) };
+  }
+  if (cfg.system.setupConnected && !seen.connected) {
+    return { id: "setup_connected", markdown: setupConnectedNotice(cfg.system.setupConnected) };
+  }
+  if (signedIn && cfg.brain.cloud === void 0) {
+    return { id: "point_at_a_brain", markdown: POINT_AT_A_BRAIN };
+  }
+  if (isSetUp(cfg) && cfg.system.guidanceVersion !== VERSION) {
+    return { id: "refresh_guidance", markdown: REFRESH_GUIDANCE };
+  }
+  if (cfg.brain.cloud !== void 0 && cfg.brain.cloud.api_url === apiUrl()) return null;
+  if (!isSetUp(cfg)) return { id: "finish_setup", markdown: FINISH_SETUP };
+  if (cfg.brain.brains.length === 0 && cfg.brain.cloud === void 0) {
+    return { id: "connect_a_brain", markdown: CONNECT_A_BRAIN };
+  }
+  return null;
+}
+async function currentNextStep() {
+  try {
+    const stored = await readCredentials().catch(() => null);
+    const cfg = await loadConfig();
+    const connected = cfg.system.setupConnected ? await connectedNoticeShown(cfg.system.setupConnected.at) : false;
+    return nextStepFor(cfg, stored !== null && stored.api_url === apiUrl(), { connected });
+  } catch {
+    return null;
+  }
+}
+var FINISH_SETUP, SETUP_NUDGE, REFRESH_GUIDANCE, CONNECT_A_BRAIN, POINT_AT_A_BRAIN, UUID;
+var init_next_step = __esm({
+  "src/lib/next-step.ts"() {
+    "use strict";
+    init_brand();
+    init_api_client();
+    init_credentials();
+    init_config();
+    init_version();
+    FINISH_SETUP = `## memgineering is installed, but not set up yet.
+
+Nothing is connected: there is no brain to read, and the agent tools on this
+machine have no memgineering guidance yet. Setup is one command:
+
+\`\`\`bash
+memgineering setup --web
+\`\`\`
+
+It does NOT wait for them. It returns in a few seconds \u2014 measured \u2014 and leaves
+a setup screen open in their browser at memgineering.com, where they choose
+everything: signing in, where the memory lives, which notes. Nothing is
+installed until they finish there, and this machine picks it up on its own.
+
+If they have not already asked you to set it up, ask them first \u2014 it opens a
+browser window on their computer. Once you run it, tell them in their language
+that the setup screen is open. It prints a short code first: show it to them,
+because the screen asks them to compare it.
+
+No browser on this machine (a server, a container, a sandbox)? Run
+\`memgineering setup --web --print-url\` and give them the link to open on the
+computer they are actually sitting at.
+
+\`setup --agent\` answers every one of those questions on their behalf, and
+\`--no-login\` answers the biggest one \u2014 no account, so the memory cannot follow
+them to another machine. Use it only when they have said they would rather you
+decided, or when this machine cannot reach a browser and \`--print-url\` is no
+use to them either.
+
+Setup's output then says how to connect their brain \u2014 create one, pick one, or
+move existing notes up.
+
+The \`memgineering-setup\` skill covers what comes after.`;
+    SETUP_NUDGE = "memgineering is installed, but not set up yet. `memgineering setup --web` opens a setup screen in their browser and does NOT wait for them \u2014 ask them first unless they asked you to set it up.\nThe full notes: run `memgineering` on its own.";
+    REFRESH_GUIDANCE = `## The guidance in your agent tools is older than this memgineering.
+
+The hub and skills this CLI installs into your tool's home were written by an
+earlier release. One command rewrites them:
+
+\`\`\`bash
+memgineering setup
+\`\`\`
+
+It does not change which brain this machine reads, or any note. Two things it
+does change, both worth knowing before it runs:
+
+- A setup-owned file your user edited is overwritten; setup names it afterwards.
+- Run with no flags where there is no terminal (an agent's shell), it keeps the
+  auto-update and hook choices recorded on this machine, and installs into
+  every agent tool it finds \u2014 \`--tools\` naming every tool they use keeps it to
+  those (a tool left out keeps its old guidance, and this notice stops
+  appearing anyway). On a machine not signed in, it starts a sign-in and prints
+  a code; \`--no-login\` declines that for a machine they keep local.
+
+If you are not sure what they chose, ask them. If you run it,
+mention it to your user in one line: it is upkeep for a tool they already set
+up, and they should not have to discover it later.
+
+Guidance files are read at the start of a session, so what changes today
+arrives in the next one.`;
+    CONNECT_A_BRAIN = `## memgineering is set up, and no brain is connected.
+
+A brain is a folder of markdown notes. Until one is connected there is nothing
+to recall and nowhere to remember. Which folder is your user's choice; the
+command is one you can run for them:
+
+\`\`\`bash
+memgineering link <their-notes-folder>   # they already keep notes
+memgineering init <path>                 # they do not \u2014 creates one, laid out
+\`\`\`
+
+\`link\` reports what would be stored before anything is indexed. An existing
+folder needs no index and no frontmatter of its own \u2014 plain markdown is a brain.
+
+Then run \`memgineering onboard\`: it prints what to ask so the brain knows whose
+it is. A brain whose \`01_BASE/\` is still template text answers almost nothing.
+
+Read \`memgineering-setup\` for accounts and which of their tools this reaches.
+
+Synced instead? \`memgineering login\`, then \`memgineering create <name>\`.`;
+    POINT_AT_A_BRAIN = `## Signed in, and this machine reads no brain yet.
+
+\`memgineering brains\` lists what is on the account.
+\`memgineering use --brain <name>\` points this machine at one.
+\`memgineering create <name>\` makes one and points here, when the account has none yet.
+`;
+    UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  }
+});
+
 // src/lib/provenance.ts
-import { execFile } from "child_process";
+import { execFile, spawn as spawn2 } from "child_process";
 import { realpath as realpath3 } from "fs/promises";
-import { dirname as dirname8, join as join23, resolve as resolve14 } from "path";
+import { dirname as dirname8, join as join24, resolve as resolve14 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { promisify } from "util";
-async function detectProvenance(selfPath) {
+async function detectProvenance(selfPath, opts = {}) {
   const entry = selfPath ?? fileURLToPath2(import.meta.url);
   const selfDir = await realpath3(dirname8(entry)).catch(() => dirname8(entry));
   if (/[\\/]_npx[\\/]|[\\/]\.npm[\\/]_cacache[\\/]/.test(selfDir)) {
@@ -7882,9 +8092,11 @@ async function detectProvenance(selfPath) {
       reason: "this is a one-off npx run, not an installed copy"
     };
   }
-  for (const manager of MANAGERS) {
-    const prefix = await prefixOf(manager.bin, manager.prefixArgs);
-    if (prefix === null) continue;
+  const deadline = opts.deadlineMs;
+  const answers = deadline === void 0 ? null : await probeAllWithin(MANAGERS.map((m) => [m.bin, m.prefixArgs]), deadline);
+  for (const [i, manager] of MANAGERS.entries()) {
+    const prefix = answers === null ? await prefixOf(manager.bin, manager.prefixArgs) : answers.prefixes[i];
+    if (prefix === null || prefix === void 0) continue;
     if (isInside2(selfDir, manager.moduleRoot(prefix))) {
       return {
         kind: manager.kind,
@@ -7895,6 +8107,15 @@ async function detectProvenance(selfPath) {
       };
     }
   }
+  if (answers?.timedOut === true) {
+    return {
+      kind: "undetermined",
+      selfDir,
+      prefix: null,
+      command: "npm i -g memgineering@latest",
+      reason: "the package managers did not answer in time to tell which one installed this copy"
+    };
+  }
   const local = selfDir.includes(`${"node_modules"}`);
   return {
     kind: local ? "local" : "unknown",
@@ -7907,6 +8128,62 @@ async function detectProvenance(selfPath) {
 function canSelfUpdate(p) {
   return p.kind === "npm" || p.kind === "pnpm" || p.kind === "bun";
 }
+async function probeAllWithin(probes, deadlineMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), deadlineMs);
+  timer.unref();
+  try {
+    const prefixes = await Promise.all(
+      probes.map(([bin, args]) => probeOnce(bin, args, controller.signal))
+    );
+    return { prefixes, timedOut: controller.signal.aborted };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function probeOnce(bin, args, signal) {
+  return new Promise((settle) => {
+    let child;
+    try {
+      child = spawn2(bin, args, { detached: true, stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      settle(null);
+      return;
+    }
+    let out = "";
+    let done = false;
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      signal.removeEventListener("abort", stop);
+      settle(value);
+    };
+    function stop() {
+      try {
+        if (process.platform === "win32" || child.pid === void 0) child.kill("SIGKILL");
+        else process.kill(-child.pid, "SIGKILL");
+      } catch {
+      }
+      child.stdout?.destroy();
+      child.unref();
+      finish(null);
+    }
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => finish(null));
+    child.on("close", (code) => {
+      const value = out.trim();
+      if (code !== 0 || value === "") {
+        finish(null);
+        return;
+      }
+      void realpath3(value).catch(() => value).then(finish);
+    });
+    if (signal.aborted) stop();
+    else signal.addEventListener("abort", stop, { once: true });
+  });
+}
 async function prefixOf(bin, args) {
   try {
     const { stdout } = await run(bin, args, { timeout: 5e3 });
@@ -7928,7 +8205,7 @@ async function unreachableByName(selfPath) {
   const p = await detectProvenance(entry);
   return p.kind === "local" || p.kind === "npx" ? p.reason : null;
 }
-var run, MANAGERS;
+var run, MANAGERS, BACKGROUND_PROBE_DEADLINE_MS;
 var init_provenance = __esm({
   "src/lib/provenance.ts"() {
     "use strict";
@@ -7938,7 +8215,7 @@ var init_provenance = __esm({
         kind: "npm",
         bin: "npm",
         prefixArgs: ["prefix", "-g"],
-        moduleRoot: (prefix) => process.platform === "win32" ? join23(prefix, "node_modules") : join23(prefix, "lib", "node_modules"),
+        moduleRoot: (prefix) => process.platform === "win32" ? join24(prefix, "node_modules") : join24(prefix, "lib", "node_modules"),
         install: "npm i -g memgineering@latest"
       },
       {
@@ -7957,6 +8234,7 @@ var init_provenance = __esm({
         install: "bun add -g memgineering"
       }
     ];
+    BACKGROUND_PROBE_DEADLINE_MS = 1500;
   }
 });
 
@@ -7972,24 +8250,29 @@ __export(setup_cloud_exports, {
   runSetupCloudChild: () => runSetupCloudChild,
   waitAndApply: () => waitAndApply
 });
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import { realpathSync as realpathSync2 } from "fs";
 import { readdir as readdir7, stat as stat6 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { basename as basename3, dirname as dirname9, join as join24, resolve as resolve15, sep as sep4 } from "path";
-async function report2(setupToken, state, detail) {
+import { basename as basename3, dirname as dirname9, join as join25, resolve as resolve15, sep as sep4 } from "path";
+async function report2(setupToken, state, detail, code) {
   try {
     await apiRequest({
       method: "POST",
       path: "/v1/setup/session/report",
-      body: { setup_token: setupToken, state, ...detail === void 0 ? {} : { detail } }
+      body: {
+        setup_token: setupToken,
+        state,
+        ...detail === void 0 ? {} : { detail },
+        ...code === void 0 ? {} : { code }
+      }
     });
   } catch {
   }
 }
 async function folderCandidates() {
   const home = homedir5();
-  const roots = ["Documents", "notes", "Notes", "Obsidian", "vault"].map((d) => join24(home, d));
+  const roots = ["Documents", "notes", "Notes", "Obsidian", "vault"].map((d) => join25(home, d));
   const found = [];
   const countNotes = async (dir) => {
     let count = 0;
@@ -7998,7 +8281,7 @@ async function folderCandidates() {
       if (entry.name.startsWith(".")) continue;
       if (entry.isFile() && /\.(md|markdown)$/i.test(entry.name)) count += 1;
       else if (entry.isDirectory()) {
-        const inner = await readdir7(join24(dir, entry.name)).catch(() => []);
+        const inner = await readdir7(join25(dir, entry.name)).catch(() => []);
         count += inner.filter((n) => /\.(md|markdown)$/i.test(n)).length;
       }
       if (count > 999) break;
@@ -8058,17 +8341,24 @@ async function applyAnswers(setupToken, claim, detected, guards = { candidates:
         ...cfg,
         system: {
           ...cfg.system,
-          setupConnected: { account_id: account.id, email: account.email, at: (/* @__PURE__ */ new Date()).toISOString() }
+          setupConnected: {
+            account_id: account.id,
+            email: account.email,
+            at: (/* @__PURE__ */ new Date()).toISOString()
+          }
         }
       });
     }
   }
-  await report2(setupToken, "applying", "\uC124\uC815\uC744 \uC4F0\uB294 \uC911\uC774\uC5D0\uC694.");
+  await report2(setupToken, "applying", "\uC124\uC815\uC744 \uC4F0\uB294 \uC911\uC774\uC5D0\uC694.", "writing_config");
   const choice = {
     tools: toolsFromAnswers(answers, detected),
     autoUpdate: answers.auto_update ? "on" : "off",
     errorTelemetry: answers.error_telemetry === null ? "undecided" : answers.error_telemetry ? "on" : "off",
-    hook: answers.hook
+    hook: answers.hook,
+    // The screen always shows the hook switch, so this is the person's answer,
+    // and a later flag-less refresh keeps it only if it is recorded as one.
+    hookAnswer: answers.hook ? "on" : "off"
   };
   await applySetup(choice, false);
   const parts = [];
@@ -8096,7 +8386,7 @@ async function applyAnswers(setupToken, claim, detected, guards = { candidates:
       const email = account?.email ?? null;
       const yes = guards.confirmUpload ? await guards.confirmUpload({ path, email }) : null;
       if (yes === true) {
-        await report2(setupToken, "applying", "\uB178\uD2B8\uB97C \uC62C\uB9AC\uB294 \uC911\uC774\uC5D0\uC694.");
+        await report2(setupToken, "applying", "\uB178\uD2B8\uB97C \uC62C\uB9AC\uB294 \uC911\uC774\uC5D0\uC694.", "uploading");
         const { pushCommand: pushCommand2 } = await Promise.resolve().then(() => (init_push(), push_exports));
         await pushCommand2().parseAsync(
           ["--vault", path, ...claim.brain?.id ? ["--brain", claim.brain.id] : []],
@@ -8119,7 +8409,12 @@ async function applyAnswers(setupToken, claim, detected, guards = { candidates:
             }
           }
         });
-        await report2(setupToken, "applying", "\uB178\uD2B8 \uC62C\uB9AC\uAE30\uB294 \uC774 \uCEF4\uD4E8\uD130\uC5D0\uC11C \uD655\uC778\uD55C \uB4A4\uC5D0 \uC2DC\uC791\uB3FC\uC694.");
+        await report2(
+          setupToken,
+          "applying",
+          "\uB178\uD2B8 \uC62C\uB9AC\uAE30\uB294 \uC774 \uCEF4\uD4E8\uD130\uC5D0\uC11C \uD655\uC778\uD55C \uB4A4\uC5D0 \uC2DC\uC791\uB3FC\uC694.",
+          "upload_waits_for_check"
+        );
         parts.push(`upload of ${path} waits for a check on this machine`);
       } else {
         parts.push(`not uploaded: ${path}`);
@@ -8189,11 +8484,12 @@ async function waitAndApply(setupToken, opts) {
           candidates: offered,
           confirmUpload: opts.confirmUpload ?? null
         });
-        await report2(setupToken, "done", "\uC124\uCE58\uB97C \uB9C8\uCCE4\uC5B4\uC694.");
+        await report2(setupToken, "done", "\uC124\uCE58\uB97C \uB9C8\uCCE4\uC5B4\uC694.", "done");
         return done;
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        await report2(setupToken, "failed", message.slice(0, 400));
+        const code = err.code === "conflict" ? "different_account" : "failed";
+        await report2(setupToken, "failed", message.slice(0, 400), code);
         throw err;
       }
     }
@@ -8205,7 +8501,7 @@ async function waitAndApply(setupToken, opts) {
       }).catch(() => null);
       if (state?.body?.folders_requested === true) {
         sentFolders = true;
-        opts.onProgress?.("\uD3F4\uB354\uB97C \uCC3E\uC544\uBCF4\uB294 \uC911\u2026");
+        opts.onProgress?.("Looking for note folders on this machine\u2026");
         const candidates = await folderCandidates();
         offered = candidates.map((c2) => c2.path);
         await apiRequest({
@@ -8236,7 +8532,7 @@ async function startSession(detected) {
   return body;
 }
 function detachChild(setupToken) {
-  const child = spawn2(process.execPath, [process.argv[1] ?? "", "setup", "--web"], {
+  const child = spawn3(process.execPath, [process.argv[1] ?? "", "setup", "--web"], {
     detached: true,
     stdio: ["pipe", "ignore", "ignore"],
     env: { ...process.env, [SETUP_CHILD_ENV]: "1" }
@@ -8255,7 +8551,7 @@ async function runSetupCloud(opts) {
   const session = await startSession(opts.detected);
   const intervalMs = Math.max(1, session.interval ?? 5) * 1e3;
   printHuman(`
-  \uC124\uCE58 \uCF54\uB4DC: ${c.bold(session.user_code)}
+  Setup code: ${c.bold(session.user_code)}
 `);
   const opened = opts.printUrl ? false : await openBrowser(session.setup_url);
   const foreground = opts.wait || process.stdout.isTTY === true && process.stderr.isTTY === true;
@@ -8271,14 +8567,14 @@ async function runSetupCloud(opts) {
       waiting: foreground
     },
     human: () => {
-      if (opened) printHuman("\uBE0C\uB77C\uC6B0\uC800\uC5D0 \uC124\uCE58 \uD654\uBA74\uC744 \uC5F4\uC5C8\uC5B4\uC694.");
+      if (opened) printHuman("Opened the setup screen in the browser.");
       else {
-        printHuman("\uBE0C\uB77C\uC6B0\uC800\uC5D0\uC11C \uC774 \uC8FC\uC18C\uB97C \uC5F4\uC5B4 \uC124\uCE58\uB97C \uB9C8\uCCD0 \uC8FC\uC138\uC694:\n");
+        printHuman("Open this link in a browser to finish the setup:\n");
         printHuman(`  ${session.setup_url}`);
       }
       printHuman(
         c.gray(
-          foreground ? "\n  \uD654\uBA74\uC5D0\uC11C \uB9C8\uCE58\uBA74 \uC5EC\uAE30\uC11C \uC774\uC5B4\uC11C \uC124\uCE58\uD560\uAC8C\uC694. \uAE30\uB2E4\uB9AC\uB294 \uAC78 \uBA48\uCD94\uB824\uBA74 Ctrl-C." : "\n  \uD654\uBA74\uC5D0\uC11C \uB9C8\uCE58\uBA74 \uC774 \uCEF4\uD4E8\uD130\uC5D0 \uC790\uB3D9\uC73C\uB85C \uC124\uCE58\uB3FC\uC694. \uCC3D\uC744 \uB2EB\uC544\uB3C4 \uAD1C\uCC2E\uC544\uC694."
+          foreground ? "\n  When the screen is done, the install continues here. Ctrl-C stops waiting." : "\n  When the screen is done, this machine installs on its own. This window can be closed."
         )
       );
     }
@@ -8296,7 +8592,7 @@ async function runSetupCloud(opts) {
     confirmUpload: interactive ? askBeforeUpload : null
   });
   if (outcome === "expired") {
-    const line = "\uC124\uCE58 \uD654\uBA74\uC774 \uB9CC\uB8CC\uB410\uC5B4\uC694. \uC544\uBB34\uAC83\uB3C4 \uBC14\uB00C\uC9C0 \uC54A\uC558\uC5B4\uC694 \u2014 `memgineering setup --web`\uC744 \uB2E4\uC2DC \uC2E4\uD589\uD558\uBA74 \uC0C8 \uD654\uBA74\uC774 \uC5F4\uB824\uC694.";
+    const line = "The setup screen expired and nothing was changed. `memgineering setup --web` opens a new one.";
     if (isJsonMode()) notice(JSON.stringify({ setup_web: "expired" }));
     else printHuman(c.gray(`
 ${line}`));
@@ -8304,10 +8600,10 @@ ${line}`));
   }
   if (isJsonMode()) notice(JSON.stringify({ setup_web: "applied" }));
   else {
-    printHuman(c.green("\n\uC124\uCE58\uB97C \uB9C8\uCCE4\uC5B4\uC694."));
+    printHuman(c.green("\nSetup finished."));
     printHuman(
       c.gray(
-        "  \uC9C0\uAE08 \uBC14\uB85C \uC4F8 \uC218 \uC788\uC5B4\uC694 \u2014 recall\uB3C4 remember\uB3C4 \uB429\uB2C8\uB2E4.\n  \uC0C8\uB85C \uC124\uCE58\uB41C \uC548\uB0B4\uBB38\uC740 \uB2E4\uC74C \uB300\uD654\uBD80\uD130 \uD568\uAED8 \uC2E4\uB824\uC694."
+        "  recall and remember work now.\n  The newly installed guidance is read from the next conversation on."
       )
     );
   }
@@ -8342,7 +8638,7 @@ async function askBeforeUpload(q) {
   const { yes } = await prompts6({
     type: "confirm",
     name: "yes",
-    message: `${q.path} \uC758 \uB178\uD2B8\uB97C ${q.email ?? "\uC774 \uACC4\uC815"} \uBE0C\uB808\uC778\uC73C\uB85C \uC62C\uB9B4\uAE4C\uC694?`,
+    message: `Upload the notes in ${q.path} to the brain on ${q.email ?? "this account"}?`,
     initial: false
   });
   return yes === true;
@@ -8377,8 +8673,8 @@ var init_setup_cloud = __esm({
 
 // src/commands/setup.ts
 import { createHash as createHash9 } from "crypto";
-import { access as access2, mkdir as mkdir15, readFile as readFile24 } from "fs/promises";
-import { dirname as dirname10, join as join25 } from "path";
+import { access as access2, mkdir as mkdir16, readFile as readFile25 } from "fs/promises";
+import { dirname as dirname10, join as join26 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command as Command40 } from "commander";
 import prompts5 from "prompts";
@@ -8403,10 +8699,11 @@ function setupCommand() {
     "after",
     [
       "",
-      "Chat apps with no shell \u2014 ChatGPT, Claude.ai, Claude Desktop, Cowork \u2014 need no",
-      `setup: add ${HOSTED_CONNECTOR_URL} as a custom connector in the app and`,
-      "sign in. It reads and writes the brain on your account (not a folder on this",
-      "machine)."
+      "Chat apps with no shell need no setup. They read and write the brain on your",
+      `account (not a folder on this machine) at ${HOSTED_CONNECTOR_URL}:`,
+      "  ChatGPT: Settings \u2192 Developer mode \u2192 add an MCP server with that URL, sign in.",
+      "  Claude.ai, Claude Desktop, Cowork: Customize \u2192 Connectors \u2192 Add custom",
+      "  connector with that URL, sign in."
     ].join("\n")
   ).action(async (opts) => {
     const detected = await detectTools();
@@ -8441,16 +8738,18 @@ function setupCommand() {
       dryRun: opts.dryRun === true
     });
     const mode = await resolveMode(opts);
-    const choice = mode.kind === "human" ? await askHuman(detected, opts) : fromFlags(detected, opts);
+    const recorded = mode.kind === "human" ? {} : await recordedChoices(detected);
+    const choice = mode.kind === "human" ? await askHuman(detected, opts) : fromFlags(detected, opts, recorded);
     const defaultsTaken = !mode.chosen ? [
-      ...opts.autoUpdate === void 0 ? ["auto-update: on"] : [],
+      // Only what nobody chose, here or on an earlier run.
+      ...opts.autoUpdate === void 0 && recorded.autoUpdate === void 0 ? ["auto-update: on"] : [],
       // Every callback this flag arms, named — on Claude Code and Codex
       // that is two (note summaries at session start, the user's own
       // rules before an edit), and saying only the first would be
       // reporting half of what was decided on their behalf. On Grok it
       // is one, at the end of a turn, and naming the other two there
       // reported callbacks that were never installed.
-      ...opts.hook === void 0 && choice?.hook ? hooksFor(choice.tools).map((h) => `${h.what}: on`) : []
+      ...opts.hook === void 0 && recorded.hook === void 0 && choice?.hook ? hooksFor(choice.tools).map((h) => `${h.what}: on`) : []
     ] : [];
     if (choice === null) {
       printHuman(c.yellow("Cancelled \u2014 nothing was changed."));
@@ -8716,6 +9015,7 @@ async function applySetup(choice, dryRun) {
       system: {
         ...cfg.system,
         autoUpdate: choice.autoUpdate,
+        ...choice.hookAnswer === void 0 ? {} : { hook: choice.hookAnswer },
         installed,
         // Stamped whether or not anything was rewritten. A run that finds every
         // file already current is exactly the run that must clear the notice —
@@ -8741,7 +9041,7 @@ async function applySetup(choice, dryRun) {
   }
   async function write2() {
     for (const tool of choice.tools) {
-      const hubPath = join25(agentHome(), tool.hubFile);
+      const hubPath = join26(agentHome(), tool.hubFile);
       const written = await injectBlock(
         hubPath,
         hub + tailFor(tool, choice.hook),
@@ -8756,8 +9056,8 @@ async function applySetup(choice, dryRun) {
       });
       if (!dryRun && written.after !== null) mark(hubPath, written.after);
       for (const skill of BRAND.subSkills) {
-        const content = await loadAsset(join25(skill, "SKILL.md"));
-        const path = join25(agentHome(), tool.skillsDir, skill, "SKILL.md");
+        const content = await loadAsset(join26(skill, "SKILL.md"));
+        const path = join26(agentHome(), tool.skillsDir, skill, "SKILL.md");
         const out = await writeIfDifferent(path, content, dryRun);
         results.push({
           tool: tool.label,
@@ -8830,6 +9130,23 @@ function globalInstallHint(reason, hooks) {
   return `${hooks ? "The hooks and the guide call" : "The guide tells your agent to run"} \`memgineering\` by name, and ${reason} \u2014
 so nothing reaches it until a global install exists: \`npm i -g memgineering\`. Nothing needs re-running after that.`;
 }
+async function recordedChoices(detected) {
+  const cfg = await loadConfig();
+  if (!isSetUp(cfg)) return {};
+  const hook = cfg.system.hook ?? await hooksArmed(detected);
+  return { autoUpdate: cfg.system.autoUpdate, ...hook === void 0 ? {} : { hook } };
+}
+async function hooksArmed(tools) {
+  const capable = tools.filter((t) => t.hooks && t.hooksFile);
+  if (capable.length === 0) return void 0;
+  for (const tool of capable) {
+    const raw = await readFile25(join26(agentHome(), ...(tool.hooksFile ?? "").split("/")), "utf8").catch(
+      () => ""
+    );
+    if (hooksFor([tool]).some((spec) => raw.includes(spec.signature))) return "on";
+  }
+  return "off";
+}
 async function resolveMode(opts) {
   if (opts.agent) return { kind: "agent", chosen: true };
   if (opts.human) {
@@ -8863,11 +9180,11 @@ async function detectTools() {
   const home = agentHome();
   const found = [];
   for (const tool of TOOLS) {
-    if (await exists2(join25(home, tool.dir))) found.push(tool);
+    if (await exists2(join26(home, tool.dir))) found.push(tool);
   }
   return found;
 }
-function fromFlags(detected, opts) {
+function fromFlags(detected, opts, recorded = {}) {
   const tools = opts.tools ? opts.tools.split(",").map((t) => t.trim().toLowerCase()).map((id) => {
     const tool = detected.find((t) => t.id === id);
     if (tool) return tool;
@@ -8886,14 +9203,16 @@ function fromFlags(detected, opts) {
       `${known.label} creates ~/${known.dir} the first time it runs. If it is installed, open it once, then run setup again. ${detectedList}`
     );
   }) : detected;
+  const hookAnswer = parseChoice(opts.hook, recorded.hook ?? "on", "--hook");
   return {
     tools,
-    autoUpdate: parseChoice(opts.autoUpdate, "on", "--auto-update"),
+    autoUpdate: parseChoice(opts.autoUpdate, recorded.autoUpdate ?? "on", "--auto-update"),
     errorTelemetry: opts.errorTelemetry === void 0 ? "undecided" : parseChoice(opts.errorTelemetry, "off", "--error-telemetry"),
     // Only Claude Code can run something at session start. For the others the
     // skill tells the agent to call resurface itself, which is why asking for
     // a hook there is not an error — it simply has nowhere to go.
-    hook: parseChoice(opts.hook, "on", "--hook") === "on" && tools.some((t) => t.hooks)
+    hook: hookAnswer === "on" && tools.some((t) => t.hooks),
+    hookAnswer
   };
 }
 function parseChoice(value, fallback, flag2) {
@@ -8952,17 +9271,19 @@ async function askHuman(detected, opts) {
     autoUpdate: answers.autoUpdate === false ? "off" : parseChoice(opts.autoUpdate, "on", "--auto-update"),
     // An aborted prompt is not an answer — undecided, never a silent yes.
     errorTelemetry: answers.errorTelemetry === void 0 ? "undecided" : answers.errorTelemetry ? "on" : "off",
-    hook: answers.hook !== false
+    hook: answers.hook !== false,
+    // Only a question that was put is an answer to record.
+    ...answers.hook === void 0 ? {} : { hookAnswer: answers.hook ? "on" : "off" }
   };
 }
 async function injectBlock(filePath, content, dryRun, weWroteThis) {
   const block = `${BRAND.hubMarkerStart}
 ${content.trimEnd()}
 ${BRAND.hubMarkerEnd}`;
-  const existing = await readFile24(filePath, "utf8").catch(() => null);
+  const existing = await readFile25(filePath, "utf8").catch(() => null);
   if (existing === null) {
     if (!dryRun) {
-      await mkdir15(dirname10(filePath), { recursive: true });
+      await mkdir16(dirname10(filePath), { recursive: true });
       await writeThenRename(filePath, `${block}
 `);
     }
@@ -9002,11 +9323,11 @@ function looksLikeOurGuide(text) {
   return text.includes("memgineering recall") && text.includes("memgineering remember");
 }
 async function writeIfDifferent(filePath, content, dryRun) {
-  const existing = await readFile24(filePath, "utf8").catch(() => null);
+  const existing = await readFile25(filePath, "utf8").catch(() => null);
   const after = fingerprint(content);
   if (existing === content) return { outcome: "unchanged", before: existing, after };
   if (!dryRun) {
-    await mkdir15(dirname10(filePath), { recursive: true });
+    await mkdir16(dirname10(filePath), { recursive: true });
     await writeThenRename(filePath, content);
   }
   return { outcome: existing === null ? "injected" : "updated", before: existing, after };
@@ -9017,8 +9338,8 @@ function hooksFor(tools) {
   );
 }
 async function installHook(spec, tool, dryRun) {
-  const settingsPath = join25(agentHome(), ...(tool.hooksFile ?? "").split("/"));
-  const raw = await readFile24(settingsPath, "utf8").catch(() => null);
+  const settingsPath = join26(agentHome(), ...(tool.hooksFile ?? "").split("/"));
+  const raw = await readFile25(settingsPath, "utf8").catch(() => null);
   let settings = {};
   if (raw !== null) {
     try {
@@ -9060,15 +9381,15 @@ async function installHook(spec, tool, dryRun) {
   }
   const next = { ...settings, hooks: { ...hooks, [spec.event]: existingGroups } };
   if (!dryRun) {
-    await mkdir15(dirname10(settingsPath), { recursive: true });
+    await mkdir16(dirname10(settingsPath), { recursive: true });
     await writeThenRename(settingsPath, `${JSON.stringify(next, null, 2)}
 `);
   }
   return raw === null ? "injected" : "updated";
 }
 async function removeHook(spec, tool, dryRun) {
-  const settingsPath = join25(agentHome(), ...(tool.hooksFile ?? "").split("/"));
-  const raw = await readFile24(settingsPath, "utf8").catch(() => null);
+  const settingsPath = join26(agentHome(), ...(tool.hooksFile ?? "").split("/"));
+  const raw = await readFile25(settingsPath, "utf8").catch(() => null);
   if (raw === null) return "unchanged";
   let parsed;
   try {
@@ -9092,7 +9413,7 @@ async function removeHook(spec, tool, dryRun) {
   return "removed";
 }
 async function loadAsset(relPath) {
-  const raw = await readFile24(join25(await assetRoot(), relPath), "utf8");
+  const raw = await readFile25(join26(await assetRoot(), relPath), "utf8");
   if (relPath === BRAND.hubFileName && raw.startsWith("---")) {
     const end = raw.indexOf("\n---", 4);
     if (end !== -1) return raw.slice(end + 4).trimStart();
@@ -9101,12 +9422,12 @@ async function loadAsset(relPath) {
 }
 async function assetRoot() {
   const here = dirname10(fileURLToPath3(import.meta.url));
-  const bundled = join25(here, "..", "assets");
-  if (await exists2(join25(bundled, BRAND.hubFileName))) return bundled;
+  const bundled = join26(here, "..", "assets");
+  if (await exists2(join26(bundled, BRAND.hubFileName))) return bundled;
   let dir = here;
   for (; ; ) {
-    const candidate = join25(dir, "packages", "skills");
-    if (await exists2(join25(candidate, BRAND.hubFileName))) return candidate;
+    const candidate = join26(dir, "packages", "skills");
+    if (await exists2(join26(candidate, BRAND.hubFileName))) return candidate;
     const parent = dirname10(dir);
     if (parent === dir) break;
     dir = parent;
@@ -9136,6 +9457,7 @@ var init_setup = __esm({
     init_setup_brain();
     init_setup_signin();
     init_config();
+    init_next_step();
     init_provenance();
     init_ui();
     init_version();
@@ -13040,12 +13362,12 @@ var BASE_FILES = [
 ];
 var HUB_PATH = "00_HUB/HUB.md";
 var TEMPLATE_SLOTS = 2;
-function capTemplates(cards, isTemplate) {
+function capTemplates(cards, isTemplate, inConflict = () => false) {
   const kept = [];
   const withheld = [];
   let templates = 0;
   for (const card of cards) {
-    if (isTemplate(card) && ++templates > TEMPLATE_SLOTS) withheld.push(card);
+    if (isTemplate(card) && !inConflict(card) && ++templates > TEMPLATE_SLOTS) withheld.push(card);
     else kept.push(card);
   }
   return { kept, withheld };
@@ -22198,7 +22520,8 @@ function recallCommand() {
           })
         );
         isScaffolding = (card) => scaffolding.has(byId.get(card.id)?.path ?? "");
-        const capped2 = capTemplates(local.memory_cards, isScaffolding);
+        const sides = new Set(local.conflicts.flatMap((conflict) => conflict.between));
+        const capped2 = capTemplates(local.memory_cards, isScaffolding, (card) => sides.has(card.id));
         templatesWithheld = capped2.withheld.length;
         result = { ...local, memory_cards: capped2.kept };
         entries = built.entries;
@@ -22393,7 +22716,7 @@ ${unsearchedLocal.map(
           if (templatesWithheld > 0) {
             printHuman(
               c.gray(
-                `  ${templatesWithheld} more untouched template${templatesWithheld === 1 ? "" : "s"} matched and ${templatesWithheld === 1 ? "is" : "are"} not shown \u2014 at most ${TEMPLATE_SLOTS} per answer.
+                `  ${templatesWithheld} more untouched template${templatesWithheld === 1 ? "" : "s"} matched and ${templatesWithheld === 1 ? "is" : "are"} not shown \u2014 at most ${TEMPLATE_SLOTS} per answer, plus any that is one side of a conflict.
 `
               )
             );
@@ -23024,205 +23347,14 @@ init_setup();
 init_brand();
 init_version();
 init_config();
-import { spawn as spawn3 } from "child_process";
+init_next_step();
+init_provenance();
+import { spawn as spawn4 } from "child_process";
 import { randomBytes as randomBytes2 } from "crypto";
-import { mkdir as mkdir18, open, readFile as readFile27, stat as stat7, unlink as unlink4 } from "fs/promises";
+import { mkdir as mkdir18, open, readFile as readFile27, rename as rename4, rm as rm8, stat as stat7, unlink as unlink4, writeFile as writeFile15 } from "fs/promises";
 import { join as join28 } from "path";
 import { Command as Command41 } from "commander";
 
-// src/lib/next-step.ts
-init_brand();
-init_api_client();
-init_credentials();
-init_config();
-init_version();
-import { mkdir as mkdir16, readFile as readFile25, writeFile as writeFile13 } from "fs/promises";
-import { join as join26 } from "path";
-function isSetUp(cfg) {
-  return Object.keys(cfg.system.installed).length > 0;
-}
-var FINISH_SETUP = `## memgineering is installed, but not set up yet.
-
-Nothing is connected: there is no brain to read, and the agent tools on this
-machine have no memgineering guidance yet. Setup is one command:
-
-\`\`\`bash
-memgineering setup --web
-\`\`\`
-
-It does NOT wait for them. It returns in a few seconds \u2014 measured \u2014 and leaves
-a setup screen open in their browser at memgineering.com, where they choose
-everything: signing in, where the memory lives, which notes. Nothing is
-installed until they finish there, and this machine picks it up on its own.
-
-If they have not already asked you to set it up, ask them first \u2014 it opens a
-browser window on their computer. Once you run it, tell them in their language
-that the setup screen is open. It prints a short code first: show it to them,
-because the screen asks them to compare it.
-
-No browser on this machine (a server, a container, a sandbox)? Run
-\`memgineering setup --web --print-url\` and give them the link to open on the
-computer they are actually sitting at.
-
-\`setup --agent\` answers every one of those questions on their behalf, and
-\`--no-login\` answers the biggest one \u2014 no account, so the memory cannot follow
-them to another machine. Use it only when they have said they would rather you
-decided, or when this machine cannot reach a browser and \`--print-url\` is no
-use to them either.
-
-Setup's output then says how to connect their brain \u2014 create one, pick one, or
-move existing notes up.
-
-The \`memgineering-setup\` skill covers what comes after.`;
-var SETUP_NUDGE = "memgineering is installed, but not set up yet. `memgineering setup --web` opens a setup screen in their browser and does NOT wait for them \u2014 ask them first unless they asked you to set it up.\nThe full notes: run `memgineering` on its own.";
-function connectedMarker(at) {
-  return join26(brandHome(), `setup-connected-shown-${at.replace(/[^0-9A-Za-z]/g, "")}`);
-}
-async function connectedNoticeShown(at) {
-  return readFile25(connectedMarker(at), "utf8").then(
-    () => true,
-    () => false
-  );
-}
-async function markConnectedNoticeShown(at) {
-  try {
-    await mkdir16(brandHome(), { recursive: true });
-    await writeFile13(connectedMarker(at), `${(/* @__PURE__ */ new Date()).toISOString()}
-`);
-  } catch {
-  }
-}
-async function claimFullSetupNotice() {
-  const marker = join26(brandHome(), "setup-notice-shown");
-  try {
-    await readFile25(marker, "utf8");
-    return false;
-  } catch {
-  }
-  try {
-    await mkdir16(brandHome(), { recursive: true });
-    await writeFile13(marker, `${(/* @__PURE__ */ new Date()).toISOString()}
-`);
-  } catch {
-  }
-  return true;
-}
-var REFRESH_GUIDANCE = `## The guidance in your agent tools is older than this memgineering.
-
-The hub and skills this CLI installs into your tool's home were written by an
-earlier release. One command rewrites them:
-
-\`\`\`bash
-memgineering setup
-\`\`\`
-
-It does not change which brain this machine reads, or any note. Two things it
-does change, both worth knowing before it runs:
-
-- A setup-owned file your user edited is overwritten; setup names it afterwards.
-- Run with no flags where there is no terminal (an agent's shell), it applies
-  setup's defaults over whatever they chose before: auto-update on, its hooks
-  on, every agent tool it finds \u2014 and on a machine not signed in, it starts a
-  sign-in and prints a code. To keep what they chose, pass it:
-  \`--auto-update off\`, \`--hook off\`, \`--no-login\` for a machine they keep
-  local, and \`--tools\` naming every tool they use (a tool left out keeps its
-  old guidance, and this notice stops appearing anyway).
-
-If you are not sure what they chose, ask them. If you run it,
-mention it to your user in one line: it is upkeep for a tool they already set
-up, and they should not have to discover it later.
-
-Guidance files are read at the start of a session, so what changes today
-arrives in the next one.`;
-var CONNECT_A_BRAIN = `## memgineering is set up, and no brain is connected.
-
-A brain is a folder of markdown notes. Until one is connected there is nothing
-to recall and nowhere to remember. Which folder is your user's choice; the
-command is one you can run for them:
-
-\`\`\`bash
-memgineering link <their-notes-folder>   # they already keep notes
-memgineering init <path>                 # they do not \u2014 creates one, laid out
-\`\`\`
-
-\`link\` reports what would be stored before anything is indexed. An existing
-folder needs no index and no frontmatter of its own \u2014 plain markdown is a brain.
-
-Then run \`memgineering onboard\`: it prints what to ask so the brain knows whose
-it is. A brain whose \`01_BASE/\` is still template text answers almost nothing.
-
-Read \`memgineering-setup\` for accounts and which of their tools this reaches.
-
-Synced instead? \`memgineering login\`, then \`memgineering create <name>\`.`;
-var POINT_AT_A_BRAIN = `## Signed in, and this machine reads no brain yet.
-
-\`memgineering brains\` lists what is on the account.
-\`memgineering use --brain <name>\` points this machine at one.
-\`memgineering create <name>\` makes one and points here, when the account has none yet.
-`;
-var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-function shellQuote(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-function confirmUploadNotice(p) {
-  const who = p.account_email ?? "the account `setup --web` connected";
-  const brain = p.brain_id && UUID.test(p.brain_id) ? ` --brain ${p.brain_id}` : "";
-  return `## Notes are waiting to be uploaded \u2014 after a check.
-
-\`memgineering setup --web\` chose to upload \`${p.path}\` to a brain on **${who}**.
-This machine has not sent them: an upload decided on the setup screen waits
-until somebody here has seen which account would receive the notes.
-
-If that is your user's account, this uploads them:
-
-\`\`\`bash
-memgineering push --vault ${shellQuote(p.path)}${brain}
-\`\`\`
-
-If it is not, \`memgineering logout\` disconnects this machine from that account
-and nothing is uploaded. If you are not sure which it is, ask them.`;
-}
-function setupConnectedNotice(c2) {
-  const who = c2.email ?? "an account with no email on record";
-  return `## This machine is signed in as **${who}**.
-
-\`memgineering setup --web\` connected it to that account. If that is not your user's account,
-\`memgineering logout\` disconnects it, and nothing they write reaches that brain.`;
-}
-function nextStepFor(cfg, signedIn = false, seen = {}) {
-  if (cfg.system.pendingUpload) {
-    return { id: "confirm_upload", markdown: confirmUploadNotice(cfg.system.pendingUpload) };
-  }
-  if (cfg.system.setupConnected && !seen.connected) {
-    return { id: "setup_connected", markdown: setupConnectedNotice(cfg.system.setupConnected) };
-  }
-  if (signedIn && cfg.brain.cloud === void 0) {
-    return { id: "point_at_a_brain", markdown: POINT_AT_A_BRAIN };
-  }
-  if (isSetUp(cfg) && cfg.system.guidanceVersion !== VERSION) {
-    return { id: "refresh_guidance", markdown: REFRESH_GUIDANCE };
-  }
-  if (cfg.brain.cloud !== void 0 && cfg.brain.cloud.api_url === apiUrl()) return null;
-  if (!isSetUp(cfg)) return { id: "finish_setup", markdown: FINISH_SETUP };
-  if (cfg.brain.brains.length === 0 && cfg.brain.cloud === void 0) {
-    return { id: "connect_a_brain", markdown: CONNECT_A_BRAIN };
-  }
-  return null;
-}
-async function currentNextStep() {
-  try {
-    const stored = await readCredentials().catch(() => null);
-    const cfg = await loadConfig();
-    const connected = cfg.system.setupConnected ? await connectedNoticeShown(cfg.system.setupConnected.at) : false;
-    return nextStepFor(cfg, stored !== null && stored.api_url === apiUrl(), { connected });
-  } catch {
-    return null;
-  }
-}
-
-// src/commands/update.ts
-init_provenance();
-
 // src/lib/update-check.ts
 init_atomic();
 init_brand();
@@ -23432,6 +23564,18 @@ async function runUpdate(opts, inherited) {
     return;
   }
   const held = await holdUpdateSlot(inherited);
+  if (held === null && await blockedBy() === "stuck") {
+    const lock = join28(brandHome(), RECLAIM_LOCK);
+    const hint = `A previous update did not finish, and clearing what it left is blocked by ${lock}. If no memgineering update is running, delete that folder and run \`memgineering update\` again.`;
+    printDual({
+      json: { ...status, provenance: provenance.kind, updated: false, reason: "update_claim_stuck", hint },
+      human: () => {
+        printHuman(`memgineering ${status.latest} is available, but a previous update's leftover claim could not be cleared.`);
+        printHuman(c.gray(hint));
+      }
+    });
+    return;
+  }
   if (held === null) {
     const started = (await claimOwner())?.split(" ")[0];
     const hint = "Another memgineering update is installing right now. Run `memgineering update` again in a few minutes \u2014 it reports whether that install worked.";
@@ -23487,10 +23631,10 @@ async function backgroundUpdateNotice(deps = {}) {
     const status = await (deps.check ?? checkForUpdate)(VERSION);
     await reportPreviousAttempt();
     if (status.updateAvailable && cfg.system.autoUpdate === "on" && isSetUp(cfg) && !process.env["CI"]) {
-      const provenance = await (deps.provenance ?? detectProvenance)();
+      const provenance = await (deps.provenance ?? (() => detectProvenance(void 0, { deadlineMs: BACKGROUND_PROBE_DEADLINE_MS })))();
       const token = newClaimToken();
       if (canSelfUpdate(provenance) && await claimUpdateSlot(token)) {
-        (deps.startUpdate ?? ((t) => startDetachedUpdate(spawn3, t)))(token);
+        (deps.startUpdate ?? ((t) => startDetachedUpdate(spawn4, t)))(token);
         notice(
           c.gray(
             `memgineering ${status.latest} is available \u2014 installing it in the background (auto-update is on). The next run uses it.`
@@ -23513,7 +23657,7 @@ async function backgroundUpdateNotice(deps = {}) {
   } catch {
   }
 }
-function startDetachedUpdate(spawnImpl = spawn3, token) {
+function startDetachedUpdate(spawnImpl = spawn4, token) {
   const child = spawnImpl(process.execPath, [process.argv[1] ?? "", "update"], {
     detached: true,
     stdio: "ignore",
@@ -23554,7 +23698,7 @@ async function holdUpdateSlot(inherited) {
 }
 var HOOK_VERBS = /* @__PURE__ */ new Set(["guard", "resurface"]);
 var UPDATE_CLAIM_MS = 15 * 6e4;
-async function claimUpdateSlot(token = newClaimToken()) {
+async function claimUpdateSlot(token = newClaimToken(), hooks = {}) {
   const path = join28(brandHome(), "update-running");
   try {
     await mkdir18(brandHome(), { recursive: true });
@@ -23567,17 +23711,86 @@ async function claimUpdateSlot(token = newClaimToken()) {
     if (err?.code !== "EEXIST") return false;
   }
   try {
-    if (Date.now() - (await stat7(path)).mtimeMs >= UPDATE_CLAIM_MS) await unlink4(path);
+    if (Date.now() - (await stat7(path)).mtimeMs >= UPDATE_CLAIM_MS) {
+      await hooks.afterObserve?.();
+      await withReclaimLock(async () => {
+        if (Date.now() - (await stat7(path)).mtimeMs < UPDATE_CLAIM_MS) return;
+        await hooks.afterRecheck?.();
+        await unlink4(path);
+      });
+    }
   } catch {
   }
   return false;
 }
+var RECLAIM_LOCK = "update-running.reclaim";
+var RECLAIM_LOCK_MAX_MS = 10 * 6e4;
+async function withReclaimLock(fn) {
+  const home = brandHome();
+  const lock = join28(home, RECLAIM_LOCK);
+  const staging = join28(home, `${RECLAIM_LOCK}.${process.pid}.${randomBytes2(4).toString("hex")}`);
+  await mkdir18(staging, { recursive: true });
+  await writeFile15(join28(staging, "owner"), `${process.pid} ${Date.now()}
+`);
+  try {
+    await rename4(staging, lock);
+  } catch {
+    await rm8(staging, { recursive: true, force: true }).catch(() => void 0);
+    await breakAbandonedLock(lock);
+    return null;
+  }
+  try {
+    return await fn();
+  } finally {
+    const aside = `${lock}.done.${randomBytes2(4).toString("hex")}`;
+    await rename4(lock, aside).then(() => rm8(aside, { recursive: true, force: true })).catch(() => void 0);
+  }
+}
+async function breakAbandonedLock(lock) {
+  try {
+    const seen = (await readFile27(join28(lock, "owner"), "utf8")).trim();
+    if (!lockAbandoned(seen)) return;
+    const aside = `${lock}.dead.${randomBytes2(4).toString("hex")}`;
+    await rename4(lock, aside);
+    const moved = (await readFile27(join28(aside, "owner"), "utf8").catch(() => "")).trim();
+    if (moved !== seen) {
+      await rename4(aside, lock).catch(() => void 0);
+      return;
+    }
+    await rm8(aside, { recursive: true, force: true });
+  } catch {
+  }
+}
+function lockAbandoned(owner, now = Date.now()) {
+  const [pidText, atText] = owner.split(" ");
+  const pid = Number(pidText);
+  const at = Number(atText);
+  if (!Number.isFinite(at) || now - at > RECLAIM_LOCK_MAX_MS) return true;
+  if (!Number.isInteger(pid) || pid <= 0) return true;
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (err) {
+    return err?.code !== "EPERM";
+  }
+}
+async function blockedBy() {
+  try {
+    const old = Date.now() - (await stat7(join28(brandHome(), "update-running"))).mtimeMs >= UPDATE_CLAIM_MS;
+    if (old) {
+      await stat7(join28(brandHome(), RECLAIM_LOCK));
+      return "stuck";
+    }
+  } catch {
+  }
+  return "in_progress";
+}
 async function reportPreviousAttempt() {
   const previous = await readUpdateState();
   if (!previous || previous.ok) return;
   notice(
     c.yellow(`\u26A0 The last update attempt did not complete: ${previous.message}`) + c.gray(
-      "\n  `memgineering update` shows why. `memgineering setup --agent --auto-update off --hook <on|off>` stops\n  these attempts \u2014 name the hook setting you want kept, because `--agent` sets that too."
+      "\n  `memgineering update` shows why. `memgineering setup --agent --auto-update off` stops\n  these attempts; the hooks stay as this machine recorded them."
     )
   );
 }
@@ -23597,7 +23810,7 @@ function reportBelowMinimum(below) {
 
 // src/commands/undo.ts
 init_src();
-import { readFile as readFile28, rm as rm8 } from "fs/promises";
+import { readFile as readFile28, rm as rm9 } from "fs/promises";
 import { join as join29 } from "path";
 import { Command as Command42 } from "commander";
 init_atomic();
@@ -23767,7 +23980,7 @@ async function reverse(brain, op, current) {
         "Nothing to take back. `memgineering log` shows what this brain recorded."
       );
     }
-    await rm8(absolute, { force: true });
+    await rm9(absolute, { force: true });
     return null;
   }
   if (op.verb === "exclude" || op.verb === "unexclude") {
@@ -24301,6 +24514,7 @@ function whoamiCommand() {
 
 // src/program.ts
 init_config();
+init_next_step();
 init_ui();
 init_brand();
 
@@ -24491,8 +24705,14 @@ async function run3(argv) {
       process.stderr.isTTY === true ? "person" : cleaned[2] === void 0 ? "full" : "brief"
     );
   }
+  let ran;
+  program.hook("preAction", (_root, action) => {
+    let command = action;
+    while (command.parent && command.parent !== program) command = command.parent;
+    ran = command === program ? void 0 : command.name();
+  });
   await program.parseAsync(cleaned);
-  if (argv[2] !== "update") await backgroundUpdateNotice(argv[2] === void 0 ? {} : { verb: argv[2] });
+  if (ran !== "update") await backgroundUpdateNotice(ran === void 0 ? {} : { verb: ran });
 }
 async function handleError(err) {
   const failure = adaptRegistryError(err) ?? err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memgineering",
-  "version": "0.25.1",
+  "version": "0.25.2",
   "private": false,
   "description": "One memory for the AI you connect. Recall, remember, and revise a brain your agents share — stored in your own folder.",
   "license": "Apache-2.0",