memgineering 0.23.1 → 0.25.0

package/dist/index.js

@@ -367,6 +367,26 @@ var init_schema = __esm({
       scope: z.string().min(1).nullable(),
       /** Id of the claim that is current for this memory, when one is declared. */
       current_claim: z.string().min(1).nullable(),
+      /**
+       * The end date the NOTE declares, for the notes that state no claim.
+       *
+       * `valid_until` lived only on `Claim`, and the mapper mints a claim only for
+       * a note carrying a `claim:` key — which `remember` has never written. So on
+       * a real brain most notes could not carry an end date that anything read:
+       * sampled six binding rules on a production brain and four had no claim at
+       * all, the two that did having been through `revise`. A date in the
+       * frontmatter of the other four was simply ignored.
+       *
+       * Optional rather than nullable, like `kind` and `binding` above and for the
+       * same reason: a note written before this existed must map to exactly the
+       * `Memory` it always did, or the regeneration test's byte comparison rewrites
+       * every cache in existence on upgrade.
+       *
+       * The claim's copy WINS where both exist — it is the more specific statement,
+       * and a note whose conclusion carries its own dates is saying something about
+       * that conclusion rather than about the file.
+       */
+      valid_until: z.string().min(1).optional(),
       status: MemoryStatusSchema,
       /**
        * Whether this memory binds what an agent does, rather than informing it.
@@ -849,8 +869,8 @@ function scopeFromPath(path) {
   return parts.length >= 2 ? parts[parts.length - 2] ?? null : null;
 }
 function titleFromPath(path) {
-  const base = path.split("/").pop() ?? path;
-  return base.replace(/\.[^.]+$/, "") || base;
+  const base2 = path.split("/").pop() ?? path;
+  return base2.replace(/\.[^.]+$/, "") || base2;
 }
 function h1Of(intro) {
   for (const line of intro.split("\n")) {
@@ -964,8 +984,8 @@ function mapNoteToMemory(input) {
   const ns = explicit ? nsRaw : {};
   const id = asString(ns["id"]) ?? path;
   const title = asString(ns["title"]) ?? asString(frontmatter?.["title"]) ?? h1Of(outline.intro) ?? titleFromPath(path);
-  const declaredScope = asString(ns["scope"]);
-  const scope = declaredScope ?? scopeFromPath(path);
+  const declaredScope2 = asString(ns["scope"]);
+  const scope = declaredScope2 ?? scopeFromPath(path);
   const summary = asString(ns["summary"]) ?? outline.description ?? firstParagraph(outline.intro) ?? firstSectionParagraph(outline.sections) ?? null;
   const memory = {
     id,
@@ -1009,11 +1029,17 @@ function mapNoteToMemory(input) {
     aliases: asStringArray(ns["aliases"]),
     entities: asStringArray(ns["entities"]),
     updated_at: asString(ns["updated_at"]) ?? asString(frontmatter?.["updated_at"]),
+    // Carried onto the memory as well as onto the claim below, because a note
+    // that states no claim gets no claim object at all — and `remember` has
+    // never written a `claim:` key, so that is most of a real brain. Written
+    // only when present, so a note without one maps byte-identically to what
+    // it always did.
+    ...asString(ns["valid_until"]) === null ? {} : { valid_until: asString(ns["valid_until"]) },
     provenance: {
       sourcePath: path,
       sourceRevision: revision,
       mapping: explicit ? "explicit" : "heuristic",
-      scopeSource: declaredScope !== null ? "explicit" : scope === null ? "none" : "path"
+      scopeSource: declaredScope2 !== null ? "explicit" : scope === null ? "none" : "path"
     }
   };
   const claims = [];
@@ -1144,7 +1170,7 @@ var init_cache_io = __esm({
   "../../packages/memory-engine/src/view/cache-io.ts"() {
     "use strict";
     init_schema();
-    SCHEMA_VERSION = 6;
+    SCHEMA_VERSION = 7;
     POLICY_VERSION = 1;
     CacheEntrySchema = z2.object({
       path: z2.string().min(1),
@@ -1759,6 +1785,12 @@ function terms(text) {
     (match) => splitMixedScript(match[0])
   );
 }
+function contentTerms(text) {
+  const all = terms(text);
+  if (all.some((t) => HANGUL.test(t))) return all;
+  const content = all.filter((t) => !LATIN_STOPWORDS.has(t));
+  return content.length > 0 ? content : all;
+}
 function indexTerms(text) {
   return [...text.normalize("NFC").toLowerCase().matchAll(TOKEN)].flatMap((match) => {
     const token = match[0];
@@ -1831,8 +1863,9 @@ function fieldScore(queryTerms, field, weight, allowLeadingOneSyllable = false)
   return score;
 }
 function searchMemories(memories, query) {
-  const q = terms(query);
+  const q = contentTerms(query);
   if (q.length === 0) return [];
+  const scale = terms(query).length;
   const scored = [];
   for (const memory of memories) {
     let score = fieldScore(q, memory.title, WEIGHTS.title, true);
@@ -1840,13 +1873,13 @@ function searchMemories(memories, query) {
     for (const entity of memory.entities) score += fieldScore(q, entity, WEIGHTS.entity);
     score += fieldScore(q, memory.summary, WEIGHTS.summary);
     score += fieldScore(q, memory.scope, WEIGHTS.scope);
-    if (score > 0) scored.push({ memory, score: score / q.length });
+    if (score > 0) scored.push({ memory, score: score / scale });
   }
   return scored.sort(
     (a, b) => b.score !== a.score ? b.score - a.score : a.memory.id < b.memory.id ? -1 : 1
   );
 }
-var WEIGHTS, TOKEN, COMPONENT_SEPARATOR, HAS_COMPONENT_SEPARATOR, LATIN_HANGUL_BOUNDARY, SUBSTRING_MIN, PARTICLES, HANGUL, ONE_SYLLABLE_TOPIC_TERMS;
+var WEIGHTS, TOKEN, COMPONENT_SEPARATOR, HAS_COMPONENT_SEPARATOR, LATIN_HANGUL_BOUNDARY, LATIN_STOPWORDS, SUBSTRING_MIN, PARTICLES, HANGUL, ONE_SYLLABLE_TOPIC_TERMS;
 var init_search = __esm({
   "../../packages/memory-engine/src/recall/search.ts"() {
     "use strict";
@@ -1855,6 +1888,120 @@ var init_search = __esm({
     COMPONENT_SEPARATOR = /[._/-]+/u;
     HAS_COMPONENT_SEPARATOR = /[._/-]/u;
     LATIN_HANGUL_BOUNDARY = new RegExp("(?<=\\p{Script=Latin})(?=\\p{Script=Hangul})|(?<=\\p{Script=Hangul})(?=\\p{Script=Latin})", "u");
+    LATIN_STOPWORDS = /* @__PURE__ */ new Set([
+      // pronouns and possessives
+      "i",
+      "me",
+      "my",
+      "mine",
+      "myself",
+      "we",
+      "us",
+      "our",
+      "ours",
+      "ourselves",
+      "you",
+      "your",
+      "yours",
+      "yourself",
+      "yourselves",
+      "he",
+      "him",
+      "his",
+      "himself",
+      "she",
+      "her",
+      "hers",
+      "herself",
+      "it",
+      "its",
+      "itself",
+      "they",
+      "them",
+      "their",
+      "theirs",
+      "themselves",
+      // determiners
+      "a",
+      "an",
+      "the",
+      "this",
+      "that",
+      "these",
+      "those",
+      "some",
+      "any",
+      "each",
+      "every",
+      // auxiliaries and modals
+      "am",
+      "is",
+      "are",
+      "was",
+      "were",
+      "be",
+      "been",
+      "being",
+      "do",
+      "does",
+      "did",
+      "have",
+      "has",
+      "had",
+      "will",
+      "would",
+      "shall",
+      "should",
+      "can",
+      "could",
+      "may",
+      "might",
+      "must",
+      // question words
+      "what",
+      "which",
+      "who",
+      "whom",
+      "whose",
+      "when",
+      "where",
+      "why",
+      "how",
+      // prepositions
+      "about",
+      "above",
+      "after",
+      "at",
+      "before",
+      "by",
+      "for",
+      "from",
+      "in",
+      "into",
+      "of",
+      "off",
+      "on",
+      "onto",
+      "over",
+      "to",
+      "under",
+      "with",
+      "without",
+      "through",
+      "during",
+      // conjunctions and particles
+      "and",
+      "but",
+      "or",
+      "nor",
+      "so",
+      "if",
+      "then",
+      "than",
+      "as",
+      "there",
+      "here"
+    ]);
     SUBSTRING_MIN = 2;
     PARTICLES = [
       "\uC774\uB77C\uB3C4",
@@ -2005,7 +2152,7 @@ function freshnessOf(memory, claims, now) {
   if (memory.status === "superseded") return "superseded";
   if (memory.status === "retired") return "retired";
   const current = claims.find((c2) => c2.id === memory.current_claim) ?? claims[0];
-  const until = current?.valid_until;
+  const until = current?.valid_until ?? memory.valid_until ?? null;
   if (until != null) {
     const t = Date.parse(until);
     if (Number.isFinite(t) && t < now.getTime()) return "expired";
@@ -2035,7 +2182,23 @@ function recall(entries, query, opts = {}) {
       (e) => (e.chunks ?? []).map((c2) => ({ memoryId: e.memory.id, label: c2.label, text: c2.text }))
     )
   ).search(queryShape.lexical);
-  const semanticHits = depth === "exact" ? [] : opts.semantic ?? [];
+  const offeredSemantic = depth === "exact" ? [] : opts.semantic ?? [];
+  const reachedByWords = /* @__PURE__ */ new Set([
+    ...cardHits.map((hit) => hit.memory.id),
+    ...chunkHits.map((hit) => hit.memoryId)
+  ]);
+  const floor = opts.meaningFloor;
+  const bestSimilarity = offeredSemantic.reduce(
+    (best, hit) => Math.max(best, Math.min(1, Math.max(0, hit.similarity))),
+    0
+  );
+  const semanticHits = floor === void 0 ? offeredSemantic : offeredSemantic.filter((hit) => {
+    if (reachedByWords.has(hit.id)) return true;
+    const s = Math.min(1, Math.max(0, hit.similarity));
+    if (floor.absolute !== void 0 && s < floor.absolute) return false;
+    if (floor.gap !== void 0 && bestSimilarity - s > floor.gap) return false;
+    return true;
+  });
   const scoreById = /* @__PURE__ */ new Map();
   for (const hit of cardHits) scoreById.set(hit.memory.id, hit.score);
   for (const hit of chunkHits) {
@@ -2045,6 +2208,14 @@ function recall(entries, query, opts = {}) {
     const similarity = Math.min(1, Math.max(0, hit.similarity));
     scoreById.set(hit.id, (scoreById.get(hit.id) ?? 0) + similarity * SEMANTIC_WEIGHT);
   }
+  const wordIds = reachedByWords;
+  const meaningIds = new Set(semanticHits.map((hit) => hit.id));
+  const matchedOf = (id) => {
+    if (opts.semantic === void 0 || depth === "exact") return void 0;
+    const words = wordIds.has(id);
+    const meaning = meaningIds.has(id);
+    return words && meaning ? "both" : words ? "words" : meaning ? "meaning" : void 0;
+  };
   const memoryById = new Map(allMemories.map((m) => [m.id, m]));
   const hits = [...scoreById.entries()].flatMap(([id, score]) => {
     const memory = memoryById.get(id);
@@ -2145,7 +2316,11 @@ function recall(entries, query, opts = {}) {
       type: memory.type,
       // The handle IS the progressive part. No claim text here, by
       // construction rather than by remembering to strip it.
-      detail_handle: `recall://${memory.id}`
+      detail_handle: `recall://${memory.id}`,
+      ...(() => {
+        const matched = matchedOf(memory.id);
+        return matched === void 0 ? {} : { matched };
+      })()
     };
   }
 }
@@ -2171,7 +2346,7 @@ function depthOf(value) {
 function boostFor(memory) {
   return (memory.binding === true ? BINDING_BOOST : 0) + (memory.kind === void 0 ? 0 : KIND_BOOST[memory.kind] ?? 0);
 }
-var RECALL_DEPTHS, RecallOptionError, DEFAULTS, BODY_WEIGHT, SEMANTIC_WEIGHT, BINDING_BOOST, KIND_BOOST, DECISION_NOUNS, DECISION_CONTEXT, DECISION_FILLERS, CURRENCY_RANK, WIDEST_ESTIMATE;
+var MEANING_ONLY_NOTE, RECALL_DEPTHS, RecallOptionError, DEFAULTS, BODY_WEIGHT, SEMANTIC_WEIGHT, BINDING_BOOST, KIND_BOOST, DECISION_NOUNS, DECISION_CONTEXT, DECISION_FILLERS, CURRENCY_RANK, WIDEST_ESTIMATE;
 var init_planner = __esm({
   "../../packages/memory-engine/src/recall/planner.ts"() {
     "use strict";
@@ -2180,6 +2355,7 @@ var init_planner = __esm({
     init_conflicts();
     init_chunks();
     init_search();
+    MEANING_ONLY_NOTE = "matched by meaning only \u2014 none of the question\u2019s words are in this note";
     RECALL_DEPTHS = ["exact", "standard"];
     RecallOptionError = class extends Error {
       hint;
@@ -2273,6 +2449,170 @@ var init_semantic = __esm({
   }
 });
 
+// ../../packages/memory-engine/src/base-templates.ts
+function base(id, title, summary, body) {
+  return [
+    "---",
+    "memgineering:",
+    `  id: ${id}`,
+    `  title: ${title}`,
+    `  summary: ${summary}`,
+    "  scope: base",
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    body,
+    ""
+  ].join("\n");
+}
+function ownEntry(record, key2) {
+  return Object.hasOwn(record, key2) ? record[key2] : void 0;
+}
+var BASE_TEMPLATES, RETIRED_BASE_TEMPLATES;
+var init_base_templates = __esm({
+  "../../packages/memory-engine/src/base-templates.ts"() {
+    "use strict";
+    BASE_TEMPLATES = {
+      "01_BASE/CRITICAL_FACTS.md": base(
+        "critical-facts",
+        "Critical facts",
+        "The few things that must never be wrong.",
+        [
+          "Keep this short enough to read every session. Anything that can be",
+          "looked up when needed belongs in a note instead.",
+          "",
+          "- "
+        ].join("\n")
+      ),
+      "01_BASE/USER.md": base(
+        "user",
+        "About me",
+        "Who I am and what context I work in.",
+        [
+          "Background, role, what you are working on, what an agent should assume",
+          "you already know.",
+          "",
+          "- "
+        ].join("\n")
+      ),
+      "01_BASE/PREFERENCES.md": base(
+        "preferences",
+        "Preferences",
+        "How I like answers, code and decisions handled.",
+        ["Style, verbosity, how much to check in, how you like code written.", "", "- "].join("\n")
+      ),
+      "01_BASE/BOUNDARIES.md": base(
+        "boundaries",
+        "Boundaries",
+        "What an agent must not do without asking me first.",
+        [
+          "Privacy, spending, anything irreversible, anything that leaves this",
+          "machine. Be specific \u2014 a boundary that has to be interpreted is one",
+          "that will be interpreted generously.",
+          "",
+          "Storage boundaries belong here too: topics you never want written into",
+          "this brain \u2014 health, beliefs, relationships, anything you name. An",
+          "agent checks this file before it records anything.",
+          "",
+          "- "
+        ].join("\n")
+      ),
+      "01_BASE/TOOLING.md": base(
+        "tooling",
+        "Tooling",
+        "The tools, machines and commands I actually use.",
+        [
+          "Editors, languages, deploy commands, where things run. Enough that an",
+          "agent does not have to guess or discover it again each time.",
+          "",
+          "- "
+        ].join("\n")
+      )
+    };
+    RETIRED_BASE_TEMPLATES = {
+      // Retired 0.11.1, when the prompt grew a storage-boundary invitation.
+      "01_BASE/BOUNDARIES.md": [
+        [
+          "---",
+          "memgineering:",
+          "  id: boundaries",
+          "  title: Boundaries",
+          "  summary: What an agent must not do without asking me first.",
+          "  scope: base",
+          "---",
+          "",
+          "# Boundaries",
+          "",
+          "Privacy, spending, anything irreversible, anything that leaves this",
+          "machine. Be specific \u2014 a boundary that has to be interpreted is one",
+          "that will be interpreted generously.",
+          "",
+          "- ",
+          ""
+        ].join("\n")
+      ]
+    };
+  }
+});
+
+// ../../packages/memory-engine/src/recall/unfilled.ts
+var UNFILLED_FIELDS;
+var init_unfilled = __esm({
+  "../../packages/memory-engine/src/recall/unfilled.ts"() {
+    "use strict";
+    init_base_templates();
+    UNFILLED_FIELDS = {
+      /** On every card from a server that has this: still the starter file, nothing written in it. */
+      card: "unfilled",
+      /**
+       * In the request: how many such cards the caller will take. Absent means no
+       * cap, so a client older than the field gets the whole ranking it always got —
+       * the same boundary `budget` draws: the client states the capability.
+       */
+      slots: "template_slots",
+      /** In the response, only when the cap left something out: how many. */
+      withheld: "templates_withheld"
+    };
+  }
+});
+
+// ../../packages/memory-engine/src/recall/query-prefix.ts
+var init_query_prefix = __esm({
+  "../../packages/memory-engine/src/recall/query-prefix.ts"() {
+    "use strict";
+  }
+});
+
+// ../../packages/memory-engine/src/recall/scope-spread.ts
+function declaredScope(memory) {
+  return memory.provenance?.scopeSource === "explicit" ? memory.scope ?? null : null;
+}
+function scopeSpread(returned, brain) {
+  const scoped = returned.filter((s) => typeof s === "string" && s !== "");
+  const distinct = new Set(scoped);
+  if (distinct.size !== 1) return null;
+  const only = [...distinct][0];
+  const others = /* @__PURE__ */ new Set();
+  for (const scope of brain) if (scope && scope !== only) others.add(scope);
+  if (others.size === 0) return null;
+  const sorted = [...others].sort((a, b) => a.localeCompare(b));
+  return {
+    scope: only,
+    cards: scoped.length,
+    of: returned.length,
+    elsewhere: sorted.slice(0, ELSEWHERE_SHOWN),
+    elsewhere_total: sorted.length
+  };
+}
+var ELSEWHERE_SHOWN;
+var init_scope_spread = __esm({
+  "../../packages/memory-engine/src/recall/scope-spread.ts"() {
+    "use strict";
+    ELSEWHERE_SHOWN = 5;
+  }
+});
+
 // ../../packages/memory-engine/src/proposal/schema.ts
 import { z as z3 } from "zod";
 function isLifecycleAction(action) {
@@ -2284,8 +2624,14 @@ function isClassifyAction(action) {
 function isBindingAction(action) {
   return action === "unbind";
 }
+function isScopeAction(action) {
+  return action === "rescope";
+}
+function isValidityAction(action) {
+  return action === "expire";
+}
 function carriesNoClaim(action) {
-  return isLifecycleAction(action) || isClassifyAction(action) || isBindingAction(action);
+  return isLifecycleAction(action) || isClassifyAction(action) || isBindingAction(action) || isScopeAction(action) || isValidityAction(action);
 }
 function isAccepted(value) {
   return typeof value === "object" && value !== null && value[ACCEPTED] === true;
@@ -2329,6 +2675,32 @@ var init_schema2 = __esm({
        * (`remember --rule`, or a `revise` that is genuinely saying something new).
        */
       "unbind",
+      /**
+       * Where a memory binds changes. Nothing it SAYS changes.
+       *
+       * `scope` is read by `declaredScopeOf` and decides which of the two rule
+       * budgets a decision is drawn from, so it is the field that answers "does
+       * this bind me here". Nothing could write it. The one live consequence:
+       * folding a project-scoped rule into an unscoped one required superseding
+       * it, which retires the loser — so the rule would have vanished everywhere
+       * except the project it was scoped to.
+       *
+       * The value is a scope NAME, or the reserved word `global`. Never null: see
+       * the refinement below for why "absent" and "widen" must not be the same
+       * value on the wire.
+       */
+      "rescope",
+      /**
+       * A memory gets an end date. It is not retired, and it still recalls.
+       *
+       * `freshnessOf` has always returned `expired` for a claim whose
+       * `valid_until` has passed, and `CURRENCY_RANK` has always ranked that just
+       * below `current` — read, ranked, and labelled, with nothing able to write
+       * it. A date-stamped fact ("Phase 1 lands by the end of October") therefore
+       * had two options, both wrong: retire it, which says it no longer holds, or
+       * leave it, which says it holds forever.
+       */
+      "expire",
       "ignore"
     ]);
     StorableActionSchema = ProposalActionSchema.exclude(["ignore"]);
@@ -2488,6 +2860,37 @@ var init_schema2 = __esm({
        * reclassify is pending — approve, reject, or let it expire first.
        */
       proposed_kind: MemoryKindSchema.nullable().default(null),
+      /**
+       * Where `rescope` moves the memory to, and null for everything else.
+       *
+       * NEVER null to mean "everywhere". That was the first design and it is the
+       * one thing this field must not do: "the caller sent no scope" and "the
+       * caller asked to widen this rule" would be the same bytes, so the schema
+       * could not require a scope on a rescope — and a request that LOST the
+       * field, an older client, a hand-built body, a proposal rebuilt from disk,
+       * would silently widen what a rule binds instead of failing.
+       *
+       * `global` is the word instead, and it is not invented here: `GLOBAL_SCOPE`
+       * is already the reserved value a rule write uses to say it holds
+       * everywhere, and `remember` already stores it as no scope at all. So the
+       * widening is spelled, the refinement below can demand it, and the patcher
+       * still writes what the thirty global rules already on a real brain look
+       * like — no key.
+       *
+       * COMPATIBILITY BOUNDARY, as for `proposed_kind`: a proposal file carrying
+       * `action: "rescope"` does not parse on a CLI built before this, and
+       * `loadProposal` throws rather than silently dropping it.
+       */
+      proposed_scope: z3.string().min(1).max(SCOPE_LIMIT).nullable().default(null),
+      /**
+       * The end date `expire` writes onto the current claim, null elsewhere.
+       *
+       * A date rather than a status: `freshnessOf` reads `valid_until` off the
+       * claim and returns `expired`, which recall already labels and ranks below
+       * `current`. Nothing here decides what expiry MEANS — that was decided
+       * years of code ago and only the writer was missing.
+       */
+      proposed_valid_until: z3.string().min(1).nullable().default(null),
       relations: ProposedRelationsSchema,
       /** Why the AI thinks this change is right. Shown at approval time. */
       reason: z3.string().min(1),
@@ -2524,7 +2927,7 @@ var init_schema2 = __esm({
         path: ["source_excerpt"]
       }
     ).refine((p) => carriesNoClaim(p.action) || p.claim !== null, {
-      message: "only retire, unretire, reclassify and unbind may omit the claim",
+      message: "only retire, unretire, reclassify, unbind, rescope and expire may omit the claim",
       path: ["claim"]
     }).refine((p) => isClassifyAction(p.action) === (p.proposed_kind !== null), {
       message: "proposed_kind belongs to reclassify, and reclassify requires one",
@@ -2532,6 +2935,18 @@ var init_schema2 = __esm({
     }).refine((p) => !isClassifyAction(p.action) || p.claim === null, {
       message: "reclassify says what sort of memory this is; it does not take a claim",
       path: ["claim"]
+    }).refine((p) => isScopeAction(p.action) === (p.proposed_scope !== null), {
+      message: "proposed_scope belongs to rescope, and rescope requires one",
+      path: ["proposed_scope"]
+    }).refine((p) => isValidityAction(p.action) === (p.proposed_valid_until !== null), {
+      message: "proposed_valid_until belongs to expire, and expire requires one",
+      path: ["proposed_valid_until"]
+    }).refine((p) => !isScopeAction(p.action) || p.claim === null, {
+      message: "rescope says where a memory binds; it does not take a claim",
+      path: ["claim"]
+    }).refine((p) => !isValidityAction(p.action) || p.claim === null, {
+      message: "expire says when a memory stops being current; it does not take a claim",
+      path: ["claim"]
     });
     ACCEPTED = /* @__PURE__ */ Symbol("memgineering.approved");
   }
@@ -3347,12 +3762,12 @@ function commit(prepared, input, opts = {}) {
   if (carriesNoClaim(parsed.action)) {
     if (parsed.claim !== null) {
       throw Object.assign(new Error(`${parsed.action} does not take a claim`), {
-        hint: isClassifyAction(parsed.action) ? `${parsed.action} says what sort of memory this is, not what it says. To change the conclusion too, use supersede.` : isBindingAction(parsed.action) ? `${parsed.action} takes a marking back and leaves the conclusion exactly as it is \u2014 that is the whole reason it exists. To change what the note says as well, use supersede.` : `${parsed.action} changes whether a memory is current, not what it says. To change the conclusion too, use supersede.`
+        hint: isClassifyAction(parsed.action) ? `${parsed.action} says what sort of memory this is, not what it says. To change the conclusion too, use supersede.` : isBindingAction(parsed.action) ? `${parsed.action} takes a marking back and leaves the conclusion exactly as it is \u2014 that is the whole reason it exists. To change what the note says as well, use supersede.` : isScopeAction(parsed.action) ? `${parsed.action} says where a memory binds, not what it says. To change the conclusion too, use supersede.` : isValidityAction(parsed.action) ? `${parsed.action} gives a memory an end date and leaves the conclusion exactly as it is. To change what the note says as well, use supersede.` : `${parsed.action} changes whether a memory is current, not what it says. To change the conclusion too, use supersede.`
       });
     }
   } else if (parsed.claim === null) {
     throw Object.assign(new Error(`${parsed.action} needs a claim`), {
-      hint: "Only retire, unretire, reclassify and unbind may omit it. They change a memory's standing, its classification or whether it binds, rather than its content."
+      hint: "Only retire, unretire, reclassify, unbind, rescope and expire may omit it. They change a memory's standing, its classification, whether it binds, where it binds or when it stops being current \u2014 rather than its content."
     });
   } else if ((parsed.action === "supersede" || parsed.action === "create") && parsed.claim.summary === null) {
     throw Object.assign(new Error(`${parsed.action} needs a summary as well as a claim`), {
@@ -3369,6 +3784,26 @@ function commit(prepared, input, opts = {}) {
       hint: "Only `reclassify` moves a memory's kind, and it does nothing else. Propose it separately, with its own reason."
     });
   }
+  if (isScopeAction(parsed.action) && parsed.proposed_scope === null) {
+    throw Object.assign(new Error(`${parsed.action} needs the scope it is proposing`), {
+      hint: `Pass a project name, or \`${GLOBAL_SCOPE}\` to say the memory holds everywhere. Widening is spelled out because it cannot be taken back by accident.`
+    });
+  }
+  if (!isScopeAction(parsed.action) && parsed.proposed_scope !== null) {
+    throw Object.assign(new Error(`${parsed.action} does not set the scope`), {
+      hint: "Only `rescope` moves where a memory binds, and it does nothing else. Propose it separately, with its own reason."
+    });
+  }
+  if (isValidityAction(parsed.action) && parsed.proposed_valid_until === null) {
+    throw Object.assign(new Error(`${parsed.action} needs the date it is proposing`), {
+      hint: "Pass an ISO date \u2014 the day the memory stops being current. It is not retired by this: recall still returns it, ranked below what is current and labelled."
+    });
+  }
+  if (!isValidityAction(parsed.action) && parsed.proposed_valid_until !== null) {
+    throw Object.assign(new Error(`${parsed.action} does not set an end date`), {
+      hint: "Only `expire` gives a memory an end date, and it does nothing else. Propose it separately, with its own reason."
+    });
+  }
   const now = opts.now ?? /* @__PURE__ */ new Date();
   const at = now.toISOString();
   const draft = {
@@ -3378,6 +3813,8 @@ function commit(prepared, input, opts = {}) {
     memory_id: parsed.memory_id,
     claim: parsed.claim,
     proposed_kind: parsed.proposed_kind,
+    proposed_scope: parsed.proposed_scope,
+    proposed_valid_until: parsed.proposed_valid_until,
     relations: parsed.relations,
     reason: parsed.reason,
     source_excerpt: parsed.source_excerpt,
@@ -3416,6 +3853,14 @@ var init_commit = __esm({
       claim: ProposedClaimSchema.nullable().default(null),
       /** What `reclassify` is reclassifying this memory AS. Only that action takes one. */
       proposed_kind: MemoryKindSchema.nullable().default(null),
+      /**
+       * Where `rescope` moves this memory to — a scope name, or the reserved word
+       * `global`. Only that action takes one, and it may not be null: see
+       * `ProposalSchema.proposed_scope` for why "absent" must not spell "widen".
+       */
+      proposed_scope: z5.string().min(1).max(SCOPE_LIMIT).nullable().default(null),
+      /** The end date `expire` writes onto the current claim. Only that action takes one. */
+      proposed_valid_until: z5.string().min(1).nullable().default(null),
       relations: ProposedRelationsSchema.default({}),
       reason: z5.string().min(1),
       /** The passage from the note that justifies this. Required to submit. */
@@ -3526,6 +3971,58 @@ function unbindInput(entry, opts = {}) {
     target_path: entry.path
   };
 }
+function rescopeInput(entry, scope, opts = {}) {
+  const wanted = scope.trim();
+  if (wanted === "") {
+    throw Object.assign(new Error("a scope cannot be empty"), {
+      hint: `Name the project this memory binds in, or \`${GLOBAL_SCOPE}\` to say it holds everywhere.`
+    });
+  }
+  if ([...wanted].length > SCOPE_LIMIT) {
+    throw Object.assign(new Error(`a scope may be at most ${SCOPE_LIMIT} characters`), {
+      hint: "A scope names a project. If it needs a sentence, it belongs in the note."
+    });
+  }
+  const declared = declaredScopeOf(entry.memory);
+  const same = isGlobalScope(wanted) ? declared === null : declared === wanted;
+  if (same) {
+    throw Object.assign(new Error(`${entry.memory.title} already binds there`), {
+      hint: "Nothing was written, and nothing needed to be."
+    });
+  }
+  return {
+    action: "rescope",
+    memory_id: entry.memory.id,
+    claim: null,
+    proposed_scope: wanted,
+    reason: opts.reason ?? `binds in ${wanted}`,
+    source_excerpt: opts.because ?? entry.memory.summary ?? entry.memory.title,
+    target_path: entry.path
+  };
+}
+function expireInput(entry, until, opts = {}) {
+  const wanted = until.trim();
+  const at = Date.parse(wanted);
+  if (!Number.isFinite(at)) {
+    throw Object.assign(new Error(`${until} is not a date`), {
+      hint: "Pass an ISO date, such as 2026-10-31 or 2026-10-31T00:00:00Z."
+    });
+  }
+  if ((entry.claims[0]?.valid_until ?? entry.memory.valid_until ?? null) === wanted) {
+    throw Object.assign(new Error(`${entry.memory.title} already ends then`), {
+      hint: "Nothing was written, and nothing needed to be."
+    });
+  }
+  return {
+    action: "expire",
+    memory_id: entry.memory.id,
+    claim: null,
+    proposed_valid_until: wanted,
+    reason: opts.reason ?? `holds until ${wanted}`,
+    source_excerpt: opts.because ?? entry.memory.summary ?? entry.memory.title,
+    target_path: entry.path
+  };
+}
 function saysNothingNew(entry, input, normalize) {
   const norm = (v) => normalize(v ?? "").trim();
   const claim = input.claim;
@@ -3565,6 +4062,8 @@ var init_curate = __esm({
   "../../packages/memory-engine/src/capture/curate.ts"() {
     "use strict";
     init_planner();
+    init_schema();
+    init_rule_budget();
     NO_REASON_GIVEN = "revised directly";
     noLifecycleReason = (action) => `${action}d directly`;
   }
@@ -3619,6 +4118,21 @@ function desiredFields(proposal, existing) {
     delete out["binding"];
     return out;
   }
+  if (isScopeAction(proposal.action)) {
+    if (proposal.proposed_scope === null) {
+      throw new Error(`${proposal.action} reached the patcher with no scope`);
+    }
+    if (isGlobalScope(proposal.proposed_scope)) delete out["scope"];
+    else out["scope"] = proposal.proposed_scope;
+    return out;
+  }
+  if (isValidityAction(proposal.action)) {
+    if (proposal.proposed_valid_until === null) {
+      throw new Error(`${proposal.action} reached the patcher with no date`);
+    }
+    out["valid_until"] = proposal.proposed_valid_until;
+    return out;
+  }
   const claim = proposal.claim;
   if (claim === null) {
     throw new Error(`${proposal.action} reached the patcher with no claim`);
@@ -3956,6 +4470,68 @@ function verifyPatch(patched, proposal, before) {
     }
     return;
   }
+  if (isScopeAction(proposal.action) || isValidityAction(proposal.action)) {
+    if (before === void 0) {
+      throw new PatchError(
+        `${proposal.action} cannot be verified without the note it started from`,
+        "This is a defect in the caller, not in your note. Nothing was written."
+      );
+    }
+    if (isScopeAction(proposal.action)) {
+      const want = proposal.proposed_scope;
+      const got = declaredScopeOf(mapped.memory);
+      const landed = isGlobalScope(want) ? got === null : got === want;
+      if (!landed) {
+        throw new PatchError(
+          "the patched note does not declare the scope that was asked for",
+          "This is a defect in the patcher, not in your note. Nothing was written."
+        );
+      }
+    } else if (
+      // Read back the way `freshnessOf` reads it: the claim's date when the
+      // note states a claim, the note's own otherwise. Asserting only on the
+      // claim would reject every note `remember` wrote, since it has never
+      // written a `claim:` key.
+      (mapped.claims[0]?.valid_until ?? mapped.memory.valid_until ?? null) !== proposal.proposed_valid_until
+    ) {
+      throw new PatchError(
+        "the patched note does not carry the end date that was asked for",
+        "This is a defect in the patcher, not in your note. Nothing was written."
+      );
+    }
+    const was = mapNoteToMemory({ path: proposal.target.path, content: before, revision: null });
+    if (was.claims[0]?.text !== mapped.claims[0]?.text) {
+      throw new PatchError(
+        `${proposal.action} changed the conclusion, which it must never do`,
+        "It changes one field and leaves what the note says exactly as it was. Nothing was written."
+      );
+    }
+    if (was.memory.summary !== mapped.memory.summary) {
+      throw new PatchError(
+        `${proposal.action} changed the summary, which it must never do`,
+        "The summary is what recall matches on, and this action does not touch what the note says. Nothing was written."
+      );
+    }
+    if (was.memory.title !== mapped.memory.title) {
+      throw new PatchError(
+        `${proposal.action} changed the title, which it must never do`,
+        "It changes one field and leaves what the note says exactly as it was. Nothing was written."
+      );
+    }
+    if (was.memory.status !== mapped.memory.status) {
+      throw new PatchError(
+        `${proposal.action} changed the status, which it must never do`,
+        "Moving where a memory binds, or saying when it stops being current, does not retire it. To take it out of the answers, use retire. Nothing was written."
+      );
+    }
+    if (was.memory.binding !== mapped.memory.binding) {
+      throw new PatchError(
+        `${proposal.action} changed whether the memory binds, which it must never do`,
+        "To take a marking back, use `revise --no-rule`. Nothing was written."
+      );
+    }
+    return;
+  }
   const supersedes = new Set(
     mapped.relations.filter((r) => r.type === "supersedes").map((r) => r.to)
   );
@@ -4031,6 +4607,8 @@ var init_patch = __esm({
   "../../packages/memory-engine/src/proposal/patch.ts"() {
     "use strict";
     init_markdown_mapping();
+    init_rule_budget();
+    init_schema();
     init_schema2();
     NAMESPACE2 = "memgineering";
     FENCE_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(\r?\n|$)/;
@@ -4073,15 +4651,15 @@ async function applyProposal(adapter, accepted) {
   const patch = computePatch(current.content, proposal);
   verifyPatch(patch.content, proposal, current.content);
   if (patch.content === current.content) {
-    const base = proposal.target.baseRevision;
-    if (base === null || base === void 0) {
+    const base2 = proposal.target.baseRevision;
+    if (base2 === null || base2 === void 0) {
       return {
         ok: false,
         reason: "revision_conflict",
         proposal: needsRebase(proposal, current.revision)
       };
     }
-    if (adapter.compareRevision(base, current.revision) === "diverged") {
+    if (adapter.compareRevision(base2, current.revision) === "diverged") {
       return {
         ok: false,
         reason: "revision_conflict",
@@ -4148,23 +4726,36 @@ function rank(entries, events, opts) {
   const recalls = events.filter((e) => !AUTOMATIC.has(e.verb));
   const here = opts.here ? recalls.filter((e) => opts.here(e)) : [];
   const hereLabel = opts.hereLabel ?? "in this folder";
-  const countIn = (source) => {
-    const counts = /* @__PURE__ */ new Map();
+  const usageIn = (source) => {
+    const usage = /* @__PURE__ */ new Map();
+    const at = (id) => {
+      let u = usage.get(id);
+      if (!u) usage.set(id, u = { opened: 0, surfaced: 0, credit: 0 });
+      return u;
+    };
     for (const event of source) {
-      for (const id of event.returned_ids) counts.set(id, (counts.get(id) ?? 0) + 1);
-      if (event.opened_id) counts.set(event.opened_id, (counts.get(event.opened_id) ?? 0) + 1);
+      if (event.verb === "recall") {
+        event.returned_ids.forEach((id, i) => {
+          const u = at(id);
+          u.surfaced += 1;
+          if (i === 0) u.credit += SURFACED_SHARE;
+        });
+      } else if (DELIBERATE.has(event.verb)) {
+        const ids = event.opened_id ? [event.opened_id] : event.returned_ids;
+        for (const id of new Set(ids)) at(id).opened += 1;
+      }
     }
-    return counts;
+    return usage;
   };
-  const hereCounts = countIn(here);
-  const anyCounts = countIn(recalls);
+  const evidence = (u) => u ? u.opened + u.credit : 0;
+  const hereUsage = usageIn(here);
+  const anyUsage = usageIn(recalls);
   const lastTouched = /* @__PURE__ */ new Map();
   for (const event of recalls) {
     const t = Date.parse(event.ts);
     if (!Number.isFinite(t)) continue;
-    for (const id of [...event.returned_ids, event.opened_id].filter(Boolean)) {
-      lastTouched.set(id, Math.max(lastTouched.get(id) ?? 0, t));
-    }
+    const touched = event.verb === "recall" ? event.returned_ids.slice(0, 1) : DELIBERATE.has(event.verb) ? [event.opened_id ?? "", ...event.returned_ids].filter(Boolean) : [];
+    for (const id of touched) lastTouched.set(id, Math.max(lastTouched.get(id) ?? 0, t));
   }
   const hasBase = entries.some((e) => e.path.startsWith("01_BASE/"));
   const scored = [];
@@ -4174,16 +4765,30 @@ function rank(entries, events, opts) {
     if (freshness === "retired") continue;
     const why = [];
     let score = 0;
-    const hereCount = hereCounts.get(id) ?? 0;
-    if (hereCount > 0) {
-      score += WEIGHT.contextRecall * Math.log2(1 + hereCount);
-      why.push(`recalled ${hereCount}\xD7 ${hereLabel}`);
-    }
-    const anyCount = (anyCounts.get(id) ?? 0) - hereCount;
-    if (anyCount > 0) {
-      score += WEIGHT.anyRecall * Math.log2(1 + anyCount);
-      if (hereCount === 0) why.push(`recalled ${anyCount}\xD7 elsewhere`);
+    const hereU = hereUsage.get(id);
+    const anyU = anyUsage.get(id);
+    const hereEvidence = evidence(hereU);
+    const elsewhereEvidence = evidence(anyU) - hereEvidence;
+    if (hereEvidence > 0) {
+      score += WEIGHT.contextRecall * Math.log2(1 + hereEvidence);
+      why.push(usageLine(hereU, hereLabel));
+    }
+    if (elsewhereEvidence > 1e-9) {
+      score += WEIGHT.anyRecall * Math.log2(1 + elsewhereEvidence);
+      if (hereEvidence === 0) {
+        why.push(
+          usageLine(
+            {
+              opened: anyU.opened - (hereU?.opened ?? 0),
+              surfaced: anyU.surfaced - (hereU?.surfaced ?? 0)
+            },
+            "elsewhere"
+          )
+        );
+      }
     }
+    const hereCount = (hereU?.opened ?? 0) + (hereU?.surfaced ?? 0);
+    const anyCount = (anyU?.opened ?? 0) + (anyU?.surfaced ?? 0) - hereCount;
     const touched = lastTouched.get(id);
     if (touched !== void 0) {
       const days = (opts.now.getTime() - touched) / 864e5;
@@ -4204,16 +4809,28 @@ function rank(entries, events, opts) {
     }
     if (score === 0 && !entry.path.startsWith("01_BASE/")) {
       score += WEIGHT.neverReached;
-      why.push("never surfaced yet");
+      why.push(
+        anyU && anyU.surfaced > 0 ? usageLine(
+          { opened: 0, surfaced: anyU.surfaced },
+          // Labelled by where it happened: all here, none here, or both —
+          // a total said "in this project" would claim the whole count.
+          !hereU?.surfaced ? "elsewhere" : hereU.surfaced === anyU.surfaced ? hereLabel : `(${hereU.surfaced}\xD7 ${hereLabel})`
+        ) : "never surfaced yet"
+      );
     }
     if (freshness !== "current") why.push(freshness);
-    if (score > 0) scored.push({ entry, score, why });
+    if (score > 0) scored.push({ entry, score, why, used: hereCount > 0 || anyCount > 0 });
   }
   return scored.sort(
     (a, b) => b.score - a.score || a.entry.memory.id.localeCompare(b.entry.memory.id)
   );
 }
-var WEIGHT, STALE_BASE_DAYS;
+function usageLine(u, where) {
+  if (u.opened === 0) return `surfaced ${u.surfaced}\xD7 ${where}, never opened`;
+  if (u.surfaced === 0) return `opened ${u.opened}\xD7 ${where}`;
+  return `opened ${u.opened}\xD7 \xB7 surfaced ${u.surfaced}\xD7 ${where}`;
+}
+var WEIGHT, STALE_BASE_DAYS, SURFACED_SHARE, DELIBERATE;
 var init_rank = __esm({
   "../../packages/memory-engine/src/resurface/rank.ts"() {
     "use strict";
@@ -4266,6 +4883,8 @@ var init_rank = __esm({
       binding: 5
     };
     STALE_BASE_DAYS = 30;
+    SURFACED_SHARE = 0.5;
+    DELIBERATE = /* @__PURE__ */ new Set(["open", "publish", "adapt", "read-public"]);
   }
 });
 
@@ -4284,6 +4903,10 @@ var init_src = __esm({
     init_reconcile();
     init_planner();
     init_semantic();
+    init_unfilled();
+    init_query_prefix();
+    init_base_templates();
+    init_scope_spread();
     init_conflicts();
     init_search();
     init_schema2();
@@ -4299,6 +4922,27 @@ var init_src = __esm({
   }
 });
 
+// src/version.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join as join4 } from "path";
+var __dir, pkgPath, VERSION;
+var init_version = __esm({
+  "src/version.ts"() {
+    "use strict";
+    __dir = dirname(fileURLToPath(import.meta.url));
+    pkgPath = join4(__dir, "..", "package.json");
+    VERSION = (() => {
+      try {
+        const parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : "0.0.0-unknown";
+      } catch {
+        return "0.0.0-unknown";
+      }
+    })();
+  }
+});
+
 // src/lib/credentials.ts
 import { mkdir as mkdir3, readFile as readFile3, unlink, writeFile as writeFile2 } from "fs/promises";
 import { join as join5 } from "path";
@@ -4473,8 +5117,8 @@ function readCause(err) {
   return { detail, retryable, nothingSent: retryable || !vetoed && preFlight };
 }
 async function apiRequest(args) {
-  const base = args.baseUrl ?? apiUrl();
-  const url = `${base}${args.path}`;
+  const base2 = args.baseUrl ?? apiUrl();
+  const url = `${base2}${args.path}`;
   let res;
   try {
     res = await fetch(url, {
@@ -4498,7 +5142,7 @@ async function apiRequest(args) {
     }
     throw memgError(
       "server_unreachable",
-      `could not reach ${base}`,
+      `could not reach ${base2}`,
       `${cause.nothingSent ? NOTHING_SENT : MAY_HAVE_ARRIVED} Underlying cause: ${cause.detail}`
     );
   }
@@ -4530,7 +5174,7 @@ async function apiRequest(args) {
   }
   throw memgError(
     "server_refused",
-    `${base} answered ${res.status} with no readable error`,
+    `${base2} answered ${res.status} with no readable error`,
     `This is not a shape this CLI knows. If MEMGINEERING_API_URL points at something other than a memgineering brain server, that would explain it. First 200 characters of the response: ${text.slice(0, 200)}`
   );
 }
@@ -4819,7 +5463,30 @@ var init_config = __esm({
          * their own words are about to be replaced. It records no content, only
          * whether the bytes are still ours.
          */
-        installed: z8.record(z8.string(), z8.string()).default({})
+        installed: z8.record(z8.string(), z8.string()).default({}),
+        /**
+         * Which release wrote the guidance that is sitting in the agent tools.
+         *
+         * The upgrade path used to be a `postinstall` script that told the agent
+         * to run `setup`. npm 12 blocks install scripts by default — measured on
+         * 12.0.2 installing this package: the script never ran and npm printed
+         * only `1 package had install scripts blocked`, which says nothing about
+         * what the script would have said. So the one channel that carried
+         * "your guidance is now out of date" is gone for every user on that npm,
+         * and nothing else noticed: the CLI upgrades itself, the hub and skills
+         * in `~/.claude`, `~/.codex` and `~/.gemini` stay at whatever release
+         * last ran setup, and both halves report success.
+         *
+         * A version rather than a digest, because this is read by a check that
+         * runs before EVERY command and may not pay for reading eight bundled
+         * assets to find out. The cost of the cheap answer is that a release
+         * which did not change any guidance still asks for one `setup` run; the
+         * cost of the expensive one is paid by every recall, forever.
+         *
+         * Absent means "written before this field existed", which is the same
+         * answer as "older than this CLI" and wants the same one command.
+         */
+        guidanceVersion: z8.string().optional()
       }).default({ autoUpdate: "on" })
     });
     EMPTY_CONFIG = ConfigSchema.parse({});
@@ -4859,7 +5526,7 @@ async function createCloudBrain(token, baseUrl, name) {
   });
   return res.body;
 }
-var call, askedFromField, cloudRecall, cloudOpen, cloudEvidence, cloudRemember, cloudUndo, cloudLog, cloudPutNote, cloudListNotes, cloudRevise, cloudBaseWrite, cloudLifecycle, cloudUnbind, cloudExclude, RANKED_BY_PROJECT, rankedOnProject, cloudResurface, cloudRules, cloudReindex;
+var call, askedFromField, cloudRecall, cloudOpen, cloudEvidence, cloudRemember, cloudUndo, cloudLog, cloudPutNote, cloudListNotes, cloudRevise, cloudBaseWrite, cloudLifecycle, cloudUnbind, cloudExclude, RANKED_BY_PROJECT, rankedOnProject, cloudResurface, cloudRescope, cloudExpire, cloudRules, cloudReindex;
 var init_cloud_brain = __esm({
   "src/lib/cloud-brain.ts"() {
     "use strict";
@@ -4884,7 +5551,8 @@ var init_cloud_brain = __esm({
       // the honest answer — a client that pre-validated against its own list
       // would report a depth as accepted and then have it silently ignored.
       ...args.depth === void 0 ? {} : { depth: args.depth },
-      ...args.budget === void 0 ? {} : { budget: args.budget }
+      ...args.budget === void 0 ? {} : { budget: args.budget },
+      ...args.templateSlots === void 0 ? {} : { [UNFILLED_FIELDS.slots]: args.templateSlots }
     });
     cloudOpen = (brain, ref, askedFrom) => call(brain, "POST", "/open", { ref, ...askedFromField(askedFrom) });
     cloudEvidence = (brain, ref) => call(brain, "POST", "/evidence", { ref });
@@ -4963,6 +5631,16 @@ var init_cloud_brain = __esm({
       ...args.limit === void 0 ? {} : { limit: args.limit },
       ...askedFromField(args.askedFrom)
     });
+    cloudRescope = (brain, args) => call(brain, "POST", "/rescope", {
+      ref: args.ref,
+      scope: args.scope,
+      ...args.reason === void 0 ? {} : { reason: args.reason }
+    });
+    cloudExpire = (brain, args) => call(brain, "POST", "/expire", {
+      ref: args.ref,
+      until: args.until,
+      ...args.reason === void 0 ? {} : { reason: args.reason }
+    });
     cloudRules = (brain, args = {}) => call(brain, "POST", "/rules", {
       ...args.limit === void 0 ? {} : { limit: args.limit },
       // The server cannot see this machine's folders, so the project it is
@@ -5834,20 +6512,6 @@ async function createBrain(path, name) {
   return { root: canonicalRoot2, indexed: built.entries.length };
 }
 function files(name) {
-  const base = (id, title, summary, body) => [
-    "---",
-    "memgineering:",
-    `  id: ${id}`,
-    `  title: ${title}`,
-    `  summary: ${summary}`,
-    "  scope: base",
-    "---",
-    "",
-    `# ${title}`,
-    "",
-    body,
-    ""
-  ].join("\n");
   return {
     "00_HUB/HUB.md": [
       "---",
@@ -5887,61 +6551,9 @@ function files(name) {
       "and rewritten without asking. A number in front means it is yours.",
       ""
     ].join("\n"),
-    "01_BASE/CRITICAL_FACTS.md": base(
-      "critical-facts",
-      "Critical facts",
-      "The few things that must never be wrong.",
-      [
-        "Keep this short enough to read every session. Anything that can be",
-        "looked up when needed belongs in a note instead.",
-        "",
-        "- "
-      ].join("\n")
-    ),
-    "01_BASE/USER.md": base(
-      "user",
-      "About me",
-      "Who I am and what context I work in.",
-      [
-        "Background, role, what you are working on, what an agent should assume",
-        "you already know.",
-        "",
-        "- "
-      ].join("\n")
-    ),
-    "01_BASE/PREFERENCES.md": base(
-      "preferences",
-      "Preferences",
-      "How I like answers, code and decisions handled.",
-      ["Style, verbosity, how much to check in, how you like code written.", "", "- "].join("\n")
-    ),
-    "01_BASE/BOUNDARIES.md": base(
-      "boundaries",
-      "Boundaries",
-      "What an agent must not do without asking me first.",
-      [
-        "Privacy, spending, anything irreversible, anything that leaves this",
-        "machine. Be specific \u2014 a boundary that has to be interpreted is one",
-        "that will be interpreted generously.",
-        "",
-        "Storage boundaries belong here too: topics you never want written into",
-        "this brain \u2014 health, beliefs, relationships, anything you name. An",
-        "agent checks this file before it records anything.",
-        "",
-        "- "
-      ].join("\n")
-    ),
-    "01_BASE/TOOLING.md": base(
-      "tooling",
-      "Tooling",
-      "The tools, machines and commands I actually use.",
-      [
-        "Editors, languages, deploy commands, where things run. Enough that an",
-        "agent does not have to guess or discover it again each time.",
-        "",
-        "- "
-      ].join("\n")
-    )
+    // The five base files come from the engine, which the hosted server reads
+    // too — one copy of what a starter template is (`base-templates.ts`).
+    ...BASE_TEMPLATES
   };
 }
 var OBSERVATIONS_DIR2, FOLDERS;
@@ -6043,8 +6655,8 @@ import { join as join17 } from "path";
 import { Command as Command13 } from "commander";
 import prompts2 from "prompts";
 function sameBasename(all, entry) {
-  const base = (entry.split("/").pop() ?? entry).normalize("NFC").toLowerCase();
-  return all.filter((p) => (p.split("/").pop() ?? "").normalize("NFC").toLowerCase() === base);
+  const base2 = (entry.split("/").pop() ?? entry).normalize("NFC").toLowerCase();
+  return all.filter((p) => (p.split("/").pop() ?? "").normalize("NFC").toLowerCase() === base2);
 }
 function spreadAcrossFolders(rows, max) {
   const seen = /* @__PURE__ */ new Set();
@@ -6470,23 +7082,23 @@ var init_open_browser = __esm({
 });
 
 // src/commands/login.ts
-import { Command as Command20 } from "commander";
+import { Command as Command21 } from "commander";
 function loginCommand() {
-  return new Command20("login").description("sign in to a hosted brain").option(
+  return new Command21("login").description("sign in to a hosted brain").option(
     "--emit-only",
     "start the sign-in, open the browser, and return immediately \u2014 THE path an agent should use on a user\u2019s behalf; the next command claims the token automatically. Prefer this over the plain form, whose wait for a human click will outlast an agent\u2019s command timeout"
   ).option("--no-browser", "do not try to open a browser \u2014 just print the link").option("--print-url", "print the approval link even when a browser opened").addHelpText(
     "after",
     "\nAgents: run `login --emit-only`, then SHOW the code in your reply. The\napproval page asks the user to check it against what you showed them,\nand they cannot if you never showed it. Do not ask the user to run a\nlogin command themselves."
   ).action(async (opts) => {
-    const base = apiUrl();
-    const already = await currentCredentials(base);
+    const base2 = apiUrl();
+    const already = await currentCredentials(base2);
     if (already) {
       printDual({
         json: {
           already_signed_in: true,
           account: { id: already.account_id, display_name: already.display_name },
-          api_url: base
+          api_url: base2
         },
         human: () => {
           printHuman(
@@ -6500,11 +7112,11 @@ function loginCommand() {
     const { pending, opened } = await beginSignIn({ browser: opts.browser !== false });
     const showUrl = !opened || opts.printUrl === true;
     if (opts.emitOnly) {
-      emit(pending, { base, opened, showUrl, blocking: false });
+      emit(pending, { base: base2, opened, showUrl, blocking: false });
       return;
     }
-    emit(pending, { base, opened, showUrl, blocking: true });
-    await waitForApproval(pending, base);
+    emit(pending, { base: base2, opened, showUrl, blocking: true });
+    await waitForApproval(pending, base2);
   });
 }
 async function beginSignIn(opts) {
@@ -6514,32 +7126,32 @@ async function beginSignIn(opts) {
   return { pending, opened };
 }
 async function signInSummary() {
-  const base = apiUrl();
+  const base2 = apiUrl();
   const stored = await readCredentials();
   const pending = await pendingOrNull();
   return {
-    signedIn: stored !== null && stored.api_url === base,
-    displayName: stored?.api_url === base ? stored?.display_name ?? null : null,
-    pendingUserCode: pending?.api_url === base ? pending.user_code : null,
-    apiUrl: base
+    signedIn: stored !== null && stored.api_url === base2,
+    displayName: stored?.api_url === base2 ? stored?.display_name ?? null : null,
+    pendingUserCode: pending?.api_url === base2 ? pending.user_code : null,
+    apiUrl: base2
   };
 }
-async function startPairing(base) {
+async function startPairing(base2) {
   const res = await apiRequest({
     method: "POST",
     path: "/v1/auth/device/code",
-    baseUrl: base
+    baseUrl: base2
   });
   const { device_code, user_code, verification_url, expires_in } = res.body ?? {};
   if (!device_code || !user_code || !verification_url) {
     throw memgError(
       "server_refused",
       "the brain server did not return a usable sign-in code",
-      `Nothing is stored. Check that MEMGINEERING_API_URL points at a memgineering brain server \u2014 it is currently ${base}.`
+      `Nothing is stored. Check that MEMGINEERING_API_URL points at a memgineering brain server \u2014 it is currently ${base2}.`
     );
   }
   return {
-    api_url: base,
+    api_url: base2,
     device_code,
     user_code,
     verification_url,
@@ -6590,7 +7202,7 @@ function emit(pending, ctx) {
     }
   });
 }
-async function waitForApproval(pending, base) {
+async function waitForApproval(pending, base2) {
   const deadline = Date.now() + BLOCKING_TIMEOUT_MS;
   progress("Waiting for approval");
   for (; ; ) {
@@ -6604,7 +7216,7 @@ async function waitForApproval(pending, base) {
     await sleep(5e3);
     let claimed;
     try {
-      claimed = await claimOnce(pending, base);
+      claimed = await claimOnce(pending, base2);
     } catch (err) {
       if (err instanceof MemgError && err.code === "server_unreachable") continue;
       throw err;
@@ -6614,7 +7226,7 @@ async function waitForApproval(pending, base) {
         json: {
           signed_in: true,
           account: { id: claimed.account_id, display_name: claimed.display_name },
-          api_url: base,
+          api_url: base2,
           registry: claimed.registry ? { username: claimed.registry.username, api_url: claimed.registry.api_url } : null
         },
         human: () => {
@@ -6667,9 +7279,9 @@ var push_exports = {};
 __export(push_exports, {
   pushCommand: () => pushCommand
 });
-import { Command as Command35 } from "commander";
+import { Command as Command36 } from "commander";
 function pushCommand() {
-  return new Command35("push").description("upload the brain on this machine to your hosted one").option("--vault <path>", "which local brain to upload").option("--brain <name>", "the hosted brain to upload into (created if it does not exist)").option("--dry-run", "list what would be uploaded and send nothing").action(async (opts) => {
+  return new Command36("push").description("upload the brain on this machine to your hosted one").option("--vault <path>", "which local brain to upload").option("--brain <name>", "the hosted brain to upload into (created if it does not exist)").option("--dry-run", "list what would be uploaded and send nothing").action(async (opts) => {
     const { brain: local } = await resolveBrain(opts.vault);
     const adapter = await openBrainOrExplain(local.root);
     const scan = await adapter.scan();
@@ -6822,28 +7434,28 @@ Nothing was deleted from \`${local.root}\` \u2014
   });
 }
 async function resolveDestination(named, root) {
-  const base = apiUrl();
-  const credentials = await requireCredentials(base);
+  const base2 = apiUrl();
+  const credentials = await requireCredentials(base2);
   const config = await loadConfig();
-  const brains = await listCloudBrains(credentials.token, base);
+  const brains = await listCloudBrains(credentials.token, base2);
   const pick = (summary) => ({
     brainId: summary.id,
     name: summary.name,
     token: credentials.token,
-    apiUrl: base
+    apiUrl: base2
   });
   if (named) {
     const found = brains.find((b) => b.name === named || b.id === named);
-    return pick(found ?? await createCloudBrain(credentials.token, base, named));
+    return pick(found ?? await createCloudBrain(credentials.token, base2, named));
   }
   const current = config.brain.cloud;
-  if (current && current.api_url === base) {
+  if (current && current.api_url === base2) {
     const found = brains.find((b) => b.id === current.id);
     if (found) return pick(found);
   }
   const fallbackName = root.split("/").filter(Boolean).pop() ?? "brain";
   const existing = brains.find((b) => b.name === fallbackName);
-  return pick(existing ?? await createCloudBrain(credentials.token, base, fallbackName));
+  return pick(existing ?? await createCloudBrain(credentials.token, base2, fallbackName));
 }
 var HELD_BACK_WORDING, printHeldBack2;
 var init_push = __esm({
@@ -7198,33 +7810,129 @@ var init_setup_signin = __esm({
   }
 });
 
-// src/commands/setup-cloud.ts
-var setup_cloud_exports = {};
-__export(setup_cloud_exports, {
-  SETUP_CHILD_ENV: () => SETUP_CHILD_ENV,
-  applyAnswers: () => applyAnswers,
-  readChildToken: () => readChildToken,
-  runSetupCloud: () => runSetupCloud,
-  runSetupCloudChild: () => runSetupCloudChild,
-  waitAndApply: () => waitAndApply
-});
-import { spawn as spawn2 } from "child_process";
-import { readdir as readdir7, stat as stat6 } from "fs/promises";
-import { homedir as homedir5 } from "os";
-import { join as join23 } from "path";
-async function report2(setupToken, state, detail) {
-  try {
-    await apiRequest({
-      method: "POST",
-      path: "/v1/setup/session/report",
-      body: { setup_token: setupToken, state, ...detail === void 0 ? {} : { detail } }
-    });
-  } catch {
-  }
-}
-async function folderCandidates() {
+// src/lib/provenance.ts
+import { execFile } from "child_process";
+import { realpath as realpath3 } from "fs/promises";
+import { dirname as dirname8, join as join23, resolve as resolve14 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { promisify } from "util";
+async function detectProvenance(selfPath) {
+  const entry = selfPath ?? fileURLToPath2(import.meta.url);
+  const selfDir = await realpath3(dirname8(entry)).catch(() => dirname8(entry));
+  if (/[\\/]_npx[\\/]|[\\/]\.npm[\\/]_cacache[\\/]/.test(selfDir)) {
+    return {
+      kind: "npx",
+      selfDir,
+      prefix: null,
+      command: "npm i -g memgineering@latest",
+      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;
+    if (isInside2(selfDir, manager.moduleRoot(prefix))) {
+      return {
+        kind: manager.kind,
+        selfDir,
+        prefix,
+        command: manager.install,
+        reason: null
+      };
+    }
+  }
+  const local = selfDir.includes(`${"node_modules"}`);
+  return {
+    kind: local ? "local" : "unknown",
+    selfDir,
+    prefix: null,
+    command: "npm i -g memgineering@latest",
+    reason: local ? "this copy is a project dependency, not a global install" : "no package manager on PATH owns the directory this copy is in \u2014 under nvm, asdf, Volta or mise that usually means a different Node version is active than the one it was installed with"
+  };
+}
+function canSelfUpdate(p) {
+  return p.kind === "npm" || p.kind === "pnpm" || p.kind === "bun";
+}
+async function prefixOf(bin, args) {
+  try {
+    const { stdout } = await run(bin, args, { timeout: 5e3 });
+    const value = stdout.trim();
+    return value === "" ? null : await realpath3(value).catch(() => value);
+  } catch {
+    return null;
+  }
+}
+function isInside2(child, parent) {
+  const c2 = resolve14(child);
+  const p = resolve14(parent);
+  return c2 === p || c2.startsWith(p.endsWith("/") ? p : `${p}/`);
+}
+async function unreachableByName(selfPath) {
+  const entry = selfPath ?? fileURLToPath2(import.meta.url);
+  const selfDir = await realpath3(dirname8(entry)).catch(() => dirname8(entry));
+  if (!/[\\/](node_modules|_npx|_cacache)[\\/]/.test(`${selfDir}/`)) return null;
+  const p = await detectProvenance(entry);
+  return p.kind === "local" || p.kind === "npx" ? p.reason : null;
+}
+var run, MANAGERS;
+var init_provenance = __esm({
+  "src/lib/provenance.ts"() {
+    "use strict";
+    run = promisify(execFile);
+    MANAGERS = [
+      {
+        kind: "npm",
+        bin: "npm",
+        prefixArgs: ["prefix", "-g"],
+        moduleRoot: (prefix) => process.platform === "win32" ? join23(prefix, "node_modules") : join23(prefix, "lib", "node_modules"),
+        install: "npm i -g memgineering@latest"
+      },
+      {
+        kind: "pnpm",
+        bin: "pnpm",
+        // `pnpm root -g` already prints the global node_modules.
+        prefixArgs: ["root", "-g"],
+        moduleRoot: (root) => root,
+        install: "pnpm add -g memgineering@latest"
+      },
+      {
+        kind: "bun",
+        bin: "bun",
+        prefixArgs: ["pm", "bin", "-g"],
+        moduleRoot: (bin) => bin,
+        install: "bun add -g memgineering"
+      }
+    ];
+  }
+});
+
+// src/commands/setup-cloud.ts
+var setup_cloud_exports = {};
+__export(setup_cloud_exports, {
+  SETUP_CHILD_ENV: () => SETUP_CHILD_ENV,
+  applyAnswers: () => applyAnswers,
+  readChildToken: () => readChildToken,
+  runSetupCloud: () => runSetupCloud,
+  runSetupCloudChild: () => runSetupCloudChild,
+  waitAndApply: () => waitAndApply
+});
+import { spawn as spawn2 } from "child_process";
+import { readdir as readdir7, stat as stat6 } from "fs/promises";
+import { homedir as homedir5 } from "os";
+import { join as join24 } from "path";
+async function report2(setupToken, state, detail) {
+  try {
+    await apiRequest({
+      method: "POST",
+      path: "/v1/setup/session/report",
+      body: { setup_token: setupToken, state, ...detail === void 0 ? {} : { detail } }
+    });
+  } catch {
+  }
+}
+async function folderCandidates() {
   const home = homedir5();
-  const roots = ["Documents", "notes", "Notes", "Obsidian", "vault"].map((d) => join23(home, d));
+  const roots = ["Documents", "notes", "Notes", "Obsidian", "vault"].map((d) => join24(home, d));
   const found = [];
   const countNotes = async (dir) => {
     let count = 0;
@@ -7233,7 +7941,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(join23(dir, entry.name)).catch(() => []);
+        const inner = await readdir7(join24(dir, entry.name)).catch(() => []);
         count += inner.filter((n) => /\.(md|markdown)$/i.test(n)).length;
       }
       if (count > 999) break;
@@ -7488,18 +8196,18 @@ 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 dirname8, join as join24 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { Command as Command39 } from "commander";
+import { dirname as dirname9, join as join25 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import { Command as Command40 } from "commander";
 import prompts5 from "prompts";
 import { homedir as homedir6 } from "os";
 function setupCommand() {
-  return new Command39("setup").description("install into your agents, and point at a brain (--dry-run to only report)").option("--agent", "non-interactive: take every answer from flags").option("--human", "interactive: choose from a list").option("--web", "open a screen in the browser and answer it there").option("--print-url", "with --web: print the URL instead of opening a browser").option(
+  return new Command40("setup").description("install into your agents, and point at a brain (--dry-run to only report)").option("--agent", "non-interactive: take every answer from flags").option("--human", "interactive: choose from a list").option("--web", "open a screen in the browser and answer it there").option("--print-url", "with --web: print the URL instead of opening a browser").option(
     "--wait",
     "with --web: block until the screen is finished, even with nobody watching the terminal"
   ).option(
     "--tools <list>",
-    "comma-separated: claude, codex, grok, gemini (default: all detected)"
+    "comma-separated: claude, codex, grok, gemini (default: all detected) \u2014 chat apps: see below"
   ).option("--auto-update <choice>", "on | off  (default: on, recommended)").option(
     "--error-telemetry <choice>",
     "on | off \u2014 anonymized crash reports; unset leaves it undecided (off) so a person can be asked later"
@@ -7509,13 +8217,22 @@ function setupCommand() {
   ).option("--login", "start a hosted-account sign-in as the first step").option("--no-browser", "with --login: print the approval link instead of opening a browser").option(
     "--no-login",
     "skip the sign-in step \u2014 everything installed here works without an account"
-  ).option("--dry-run", "report what would change, write nothing").option("--silent", "only speak if something changed").action(async (opts) => {
+  ).option("--dry-run", "report what would change, write nothing").option("--silent", "only speak if something changed").addHelpText(
+    "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)."
+    ].join("\n")
+  ).action(async (opts) => {
     const detected = await detectTools();
     if (detected.length === 0) {
       throw memgError(
         "invalid_input",
         "no supported agent tools found on this machine",
-        "memgineering installs into Claude Code (~/.claude), Codex (~/.codex), Grok (~/.grok) or Antigravity (~/.gemini). Install one of those first, then run setup again."
+        `memgineering installs into ${SUPPORTED_LIST}. Each is found by the folder it creates the first time it runs, so a tool installed but never opened is not found yet \u2014 open it once, then run setup again. If none is installed, install one first.`
       );
     }
     if (opts.web) {
@@ -7545,11 +8262,13 @@ function setupCommand() {
     const choice = mode.kind === "human" ? await askHuman(detected, opts) : fromFlags(detected, opts);
     const defaultsTaken = !mode.chosen ? [
       ...opts.autoUpdate === void 0 ? ["auto-update: on"] : [],
-      // Both of them, named. This one flag arms two callbacks — note
-      // summaries at session start, and the user's own rules before an
-      // edit — and saying only the first would be reporting half of what
-      // was decided on their behalf.
-      ...opts.hook === void 0 && choice?.hook ? ["session-start hook: on", "before-edit hook: 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`) : []
     ] : [];
     if (choice === null) {
       printHuman(c.yellow("Cancelled \u2014 nothing was changed."));
@@ -7562,9 +8281,14 @@ function setupCommand() {
     const changed = results.filter((r) => r.result !== "unchanged" && r.result !== "refused");
     const brains = (await loadConfig()).brain.brains;
     const brainStep = await runBrainStep(signIn, opts.dryRun === true);
+    const notByName = opts.dryRun !== true ? await unreachableByName() : null;
+    const hooksLanded = choice.hook && results.some(
+      (r) => Object.values(HOOK_WHAT).includes(r.what) && r.result !== "refused" && r.result !== "removed"
+    );
     const hints = [
       ...refusals.length > 0 ? [REFUSAL_HINT] : [],
       ...duplicated.length > 0 ? [DUPLICATE_HINT] : [],
+      ...notByName !== null ? [globalInstallHint(notByName, hooksLanded)] : [],
       /*
        * Local mode only, and that condition is the point of it.
        *
@@ -7603,6 +8327,10 @@ function setupCommand() {
          */
         ...agentHome() !== homedir6() ? { agent_home: agentHome() } : {},
         tools: choice.tools.map((t) => t.id),
+        // `tools` is what was asked for; this is where the guide actually
+        // stands after the run. They differ exactly when a guide was refused.
+        registered: registeredTools(choice.tools, results).map((t) => t.id),
+        ...notByName !== null ? { global_install_needed: notByName } : {},
         auto_update: choice.autoUpdate,
         error_telemetry: choice.errorTelemetry,
         hook: choice.hook,
@@ -7652,7 +8380,7 @@ function setupCommand() {
         }
         printSignInStep(signIn);
         printBrainStep(brainStep);
-        printHuman(`Registered with ${choice.tools.map((t) => t.label).join(", ")}.
+        printHuman(`${registrationLine(choice.tools, results)}
 `);
         const edited = results.filter((r) => r.edited === true);
         if (edited.length > 0) {
@@ -7669,14 +8397,35 @@ function setupCommand() {
         if (choice.errorTelemetry !== "undecided") {
           printHuman(c.gray(`  error-telemetry: ${choice.errorTelemetry}`));
         }
-        if (choice.hook) {
-          printHuman(c.gray("  resurface runs at session start"));
+        const armed = (what) => choice.tools.filter(
+          (t) => results.some(
+            (r) => r.tool === t.label && r.what === what && r.result !== "refused" && r.result !== "removed"
+          )
+        );
+        const atStart = choice.hook ? armed(HOOK_WHAT.sessionStart) : [];
+        const atStop = choice.hook ? armed(HOOK_WHAT.endOfTurn) : [];
+        const once = notByName !== null ? ", once memgineering is installed globally (below)" : "";
+        if (atStop.length > 0) {
+          printHuman(
+            c.gray(
+              `  your rules are shown at the end of each turn on ${atStop.map((t) => t.label).join(", ")}${once} \u2014
+    nothing there reaches the model earlier, so a turn that breaks one is corrected
+    in the next.`
+            )
+          );
+        }
+        if (atStart.length > 0) {
+          printHuman(
+            c.gray(
+              `  resurface runs at session start on ${atStart.map((t) => t.label).join(", ")}${once}`
+            )
+          );
           printHuman(
             c.gray(
-              "    \u2192 this puts a few note summaries into every new session, unasked.\n      Anything you would not want surfacing there: `memgineering exclude <path>`.\n      Turn it back off with `memgineering setup --agent --hook off`."
+              "    \u2192 this puts a few note summaries into every new session, unasked.\n      Anything you would not want surfacing there: `memgineering exclude <path>`."
             )
           );
-          if (choice.tools.some((t) => t.id === "codex")) {
+          if (atStart.some((t) => t.id === "codex")) {
             printHuman(
               c.gray(
                 "    \u2192 Codex will ask you to review these hooks once, next time it\n      starts: press `t` to trust them. Until you do, neither one runs,\n      and an upgrade that changes a hook asks again."
@@ -7684,6 +8433,19 @@ function setupCommand() {
             );
           }
         }
+        if (atStart.length > 0 || atStop.length > 0) {
+          printHuman(
+            c.gray("  Turn the hooks back off with `memgineering setup --agent --hook off`.")
+          );
+        }
+        if (notByName !== null) {
+          printHuman(
+            c.yellow(
+              `
+  ${globalInstallHint(notByName, hooksLanded).split("\n").join("\n  ")}`
+            )
+          );
+        }
         const removed = results.filter((r) => r.result === "removed");
         if (!choice.hook && removed.length > 0) {
           printHuman(c.gray(`  removed: ${label(removed)}`));
@@ -7716,7 +8478,7 @@ function setupCommand() {
         const codexHooksPending = choice.hook && choice.tools.some((t) => t.id === "codex");
         printHuman(
           c.bold(
-            codexHooksPending ? "\n  Ready to use now \u2014 recall and remember work; the hooks start once\n  Codex has asked you about them." : "\n  Ready to use now \u2014 recall, remember and the hooks all work."
+            notByName !== null ? hooksLanded ? "\n  Installed \u2014 the hooks, and an agent following the guide, start working\n  once memgineering is installed globally." : "\n  Installed \u2014 an agent following the guide starts working once\n  memgineering is installed globally." : codexHooksPending ? "\n  Ready to use now \u2014 recall and remember work; the hooks start once\n  Codex has asked you about them." : "\n  Ready to use now \u2014 recall, remember and the hooks all work."
           )
         );
         printHuman(
@@ -7773,6 +8535,11 @@ async function applySetup(choice, dryRun) {
         ...cfg.system,
         autoUpdate: choice.autoUpdate,
         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 —
+        // recording only on a change would leave `refresh_guidance` firing
+        // forever on the release where the guidance happened not to move.
+        guidanceVersion: VERSION,
         // 'undecided' means nobody answered THIS run — it must not erase an
         // answer somebody gave in an earlier one.
         ...choice.errorTelemetry !== "undecided" ? { errorTelemetry: choice.errorTelemetry } : {}
@@ -7786,13 +8553,13 @@ async function applySetup(choice, dryRun) {
   };
   const keyOf = (path) => path.startsWith(agentHome()) ? path.slice(agentHome().length + 1) : path;
   try {
-    return await write();
+    return await write2();
   } finally {
     await persist();
   }
-  async function write() {
+  async function write2() {
     for (const tool of choice.tools) {
-      const hubPath = join24(agentHome(), tool.hubFile);
+      const hubPath = join25(agentHome(), tool.hubFile);
       const written = await injectBlock(
         hubPath,
         hub + tailFor(tool, choice.hook),
@@ -7807,8 +8574,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(join24(skill, "SKILL.md"));
-        const path = join24(agentHome(), tool.skillsDir, skill, "SKILL.md");
+        const content = await loadAsset(join25(skill, "SKILL.md"));
+        const path = join25(agentHome(), tool.skillsDir, skill, "SKILL.md");
         const out = await writeIfDifferent(path, content, dryRun);
         results.push({
           tool: tool.label,
@@ -7853,6 +8620,34 @@ ${surfacedForYou && rulesForYou ? `Two moments matter here, and a hook covers ea
 The skills named above are files at \`${tool.skillsDir}/memgineering-<name>/SKILL.md\`. Your host may list a skill by name with its description trimmed away, in which case the name is all you get \u2014 read the file rather than assuming there is nothing there.${skills}
 `;
 }
+function registeredTools(tools, results) {
+  return tools.filter(
+    (t) => results.some((r) => r.tool === t.label && r.what === "guide" && r.result !== "refused")
+  );
+}
+function registrationLine(tools, results) {
+  const registered = registeredTools(tools, results);
+  const notRegistered = tools.filter((t) => !registered.includes(t));
+  const skipped = (t) => results.filter((r) => r.tool === t.label && r.result === "refused").length;
+  const names = (ts) => ts.map((t) => t.label).join(", ");
+  const parts = [];
+  if (registered.length > 0) {
+    const partial = registered.filter((t) => skipped(t) > 0);
+    parts.push(
+      `Registered with ${names(registered)}` + (partial.length > 0 ? ` \u2014 but ${partial.map((t) => `${skipped(t)} file(s) for ${t.label}`).join(", ")} could not be written, listed below` : "")
+    );
+  }
+  if (notRegistered.length > 0) {
+    parts.push(
+      `Not registered with ${names(notRegistered)} \u2014 its guide could not be written, listed below`
+    );
+  }
+  return `${parts.join(". ")}.`;
+}
+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 resolveMode(opts) {
   if (opts.agent) return { kind: "agent", chosen: true };
   if (opts.human) {
@@ -7886,21 +8681,28 @@ async function detectTools() {
   const home = agentHome();
   const found = [];
   for (const tool of TOOLS) {
-    if (await exists2(join24(home, tool.dir))) found.push(tool);
+    if (await exists2(join25(home, tool.dir))) found.push(tool);
   }
   return found;
 }
 function fromFlags(detected, opts) {
   const tools = opts.tools ? opts.tools.split(",").map((t) => t.trim().toLowerCase()).map((id) => {
     const tool = detected.find((t) => t.id === id);
-    if (!tool) {
+    if (tool) return tool;
+    const detectedList = `Detected: ${detected.map((t) => t.id).join(", ") || "none"}. Omit --tools to use all of them.`;
+    const known = TOOLS.find((t) => t.id === id);
+    if (!known) {
       throw memgError(
         "invalid_input",
-        `not installed on this machine: ${id}`,
-        `Detected: ${detected.map((t) => t.id).join(", ") || "none"}. Omit --tools to use all of them.`
+        `unknown tool: ${id}`,
+        `Supported: ${TOOLS.map((t) => t.id).join(", ")}. ${detectedList}`
       );
     }
-    return tool;
+    throw memgError(
+      "invalid_input",
+      `${known.label} not found on this machine: no ~/${known.dir} yet`,
+      `${known.label} creates ~/${known.dir} the first time it runs. If it is installed, open it once, then run setup again. ${detectedList}`
+    );
   }) : detected;
   return {
     tools,
@@ -7978,7 +8780,7 @@ ${BRAND.hubMarkerEnd}`;
   const existing = await readFile24(filePath, "utf8").catch(() => null);
   if (existing === null) {
     if (!dryRun) {
-      await mkdir15(dirname8(filePath), { recursive: true });
+      await mkdir15(dirname9(filePath), { recursive: true });
       await writeThenRename(filePath, `${block}
 `);
     }
@@ -8022,13 +8824,18 @@ async function writeIfDifferent(filePath, content, dryRun) {
   const after = fingerprint(content);
   if (existing === content) return { outcome: "unchanged", before: existing, after };
   if (!dryRun) {
-    await mkdir15(dirname8(filePath), { recursive: true });
+    await mkdir15(dirname9(filePath), { recursive: true });
     await writeThenRename(filePath, content);
   }
   return { outcome: existing === null ? "injected" : "updated", before: existing, after };
 }
+function hooksFor(tools) {
+  return HOOKS.filter(
+    (h) => tools.some((t) => t.hooks && (h.tools ?? DEFAULT_HOOK_TOOLS).includes(t.id))
+  );
+}
 async function installHook(spec, tool, dryRun) {
-  const settingsPath = join24(agentHome(), ...(tool.hooksFile ?? "").split("/"));
+  const settingsPath = join25(agentHome(), ...(tool.hooksFile ?? "").split("/"));
   const raw = await readFile24(settingsPath, "utf8").catch(() => null);
   let settings = {};
   if (raw !== null) {
@@ -8071,14 +8878,14 @@ async function installHook(spec, tool, dryRun) {
   }
   const next = { ...settings, hooks: { ...hooks, [spec.event]: existingGroups } };
   if (!dryRun) {
-    await mkdir15(dirname8(settingsPath), { recursive: true });
+    await mkdir15(dirname9(settingsPath), { recursive: true });
     await writeThenRename(settingsPath, `${JSON.stringify(next, null, 2)}
 `);
   }
   return raw === null ? "injected" : "updated";
 }
 async function removeHook(spec, tool, dryRun) {
-  const settingsPath = join24(agentHome(), ...(tool.hooksFile ?? "").split("/"));
+  const settingsPath = join25(agentHome(), ...(tool.hooksFile ?? "").split("/"));
   const raw = await readFile24(settingsPath, "utf8").catch(() => null);
   if (raw === null) return "unchanged";
   let parsed;
@@ -8103,7 +8910,7 @@ async function removeHook(spec, tool, dryRun) {
   return "removed";
 }
 async function loadAsset(relPath) {
-  const raw = await readFile24(join24(await assetRoot(), relPath), "utf8");
+  const raw = await readFile24(join25(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();
@@ -8111,14 +8918,14 @@ async function loadAsset(relPath) {
   return raw;
 }
 async function assetRoot() {
-  const here = dirname8(fileURLToPath2(import.meta.url));
-  const bundled = join24(here, "..", "assets");
-  if (await exists2(join24(bundled, BRAND.hubFileName))) return bundled;
+  const here = dirname9(fileURLToPath3(import.meta.url));
+  const bundled = join25(here, "..", "assets");
+  if (await exists2(join25(bundled, BRAND.hubFileName))) return bundled;
   let dir = here;
   for (; ; ) {
-    const candidate = join24(dir, "packages", "skills");
-    if (await exists2(join24(candidate, BRAND.hubFileName))) return candidate;
-    const parent = dirname8(dir);
+    const candidate = join25(dir, "packages", "skills");
+    if (await exists2(join25(candidate, BRAND.hubFileName))) return candidate;
+    const parent = dirname9(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -8136,7 +8943,7 @@ async function exists2(path) {
     return false;
   }
 }
-var TOOLS, REFUSAL_HINT, DUPLICATE_HINT, HOOK_TIMEOUT_S, DEFAULT_HOOK_TOOLS, HOOKS;
+var TOOLS, HOSTED_CONNECTOR_URL, SUPPORTED_LIST, REFUSAL_HINT, DUPLICATE_HINT, HOOK_TIMEOUT_S, DEFAULT_HOOK_TOOLS, HOOK_WHAT, HOOKS;
 var init_setup = __esm({
   "src/commands/setup.ts"() {
     "use strict";
@@ -8147,7 +8954,9 @@ var init_setup = __esm({
     init_setup_brain();
     init_setup_signin();
     init_config();
+    init_provenance();
     init_ui();
+    init_version();
     TOOLS = [
       {
         id: "claude",
@@ -8215,20 +9024,27 @@ var init_setup = __esm({
         hooksFile: ".grok/hooks/memgineering.json"
       }
     ];
+    HOSTED_CONNECTOR_URL = "https://mcp.memgineering.com/mcp";
+    SUPPORTED_LIST = TOOLS.map((t) => `${t.label} (\`${t.id}\`, ~/${t.dir})`).join(", ");
     REFUSAL_HINT = `Either a guide setup wrote is still there with its markers removed, or a settings file is not valid JSON. Everything else in this run was applied.
 For a guide: put ${BRAND.hubMarkerStart} and ${BRAND.hubMarkerEnd} back around that block, or delete the block, then run setup again.`;
     DUPLICATE_HINT = "That file already looked like it held a memgineering guide with no markers around it, so the new one was appended below rather than replacing it.\nIf an older copy is now sitting above it, delete that copy \u2014 two guides means both are in every session. If those lines are your own writing, nothing is wrong.";
     HOOK_TIMEOUT_S = Math.ceil(HOOK_DEADLINE_MS / 1e3) + 3;
     DEFAULT_HOOK_TOOLS = ["claude", "codex"];
+    HOOK_WHAT = {
+      sessionStart: "session-start hook",
+      beforeEdit: "before-edit hook",
+      endOfTurn: "end-of-turn hook"
+    };
     HOOKS = [
       {
-        what: "session-start hook",
+        what: HOOK_WHAT.sessionStart,
         event: "SessionStart",
         command: `memgineering resurface --limit 5 --deadline ${HOOK_DEADLINE_MS} || true`,
         signature: "memgineering resurface"
       },
       {
-        what: "before-edit hook",
+        what: HOOK_WHAT.beforeEdit,
         event: "PreToolUse",
         // Both lists are subsets of what `guard` filters on, so the process does
         // not start at all for a call it would ignore.
@@ -8279,7 +9095,7 @@ For a guide: put ${BRAND.hubMarkerStart} and ${BRAND.hubMarkerEnd} back around t
          * because speaking here keeps the agent working — which is why the report
          * says so rather than leaving somebody to notice.
          */
-        what: "end-of-turn hook",
+        what: HOOK_WHAT.endOfTurn,
         event: "Stop",
         command: "memgineering guard --at stop || true",
         signature: "memgineering guard --at stop",
@@ -8293,7 +9109,7 @@ For a guide: put ${BRAND.hubMarkerStart} and ${BRAND.hubMarkerEnd} back around t
 import net from "net";
 
 // src/program.ts
-import { Command as Command45 } from "commander";
+import { Command as Command46 } from "commander";
 
 // src/help.ts
 init_ui();
@@ -8337,7 +9153,18 @@ var COMMAND_GROUPS = [
   {
     title: "CURATION",
     blurb: "occasional \u2014 correct what is remembered and what is read",
-    commands: ["retire", "unretire", "retract", "exclude", "unexclude", "consolidate", "propose", "proposals"]
+    commands: [
+      "retire",
+      "unretire",
+      "rescope",
+      "expire",
+      "retract",
+      "exclude",
+      "unexclude",
+      "consolidate",
+      "propose",
+      "proposals"
+    ]
   },
   {
     title: "ACCOUNT",
@@ -8429,26 +9256,10 @@ init_errors();
 // src/lib/error-reporter.ts
 init_src();
 init_errors();
-import { homedir as homedir3, platform } from "os";
-
-// src/version.ts
-import { readFileSync } from "fs";
-import { fileURLToPath } from "url";
-import { dirname, join as join4 } from "path";
-var __dir = dirname(fileURLToPath(import.meta.url));
-var pkgPath = join4(__dir, "..", "package.json");
-var VERSION = (() => {
-  try {
-    const parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
-    return typeof parsed.version === "string" ? parsed.version : "0.0.0-unknown";
-  } catch {
-    return "0.0.0-unknown";
-  }
-})();
-
-// src/lib/error-reporter.ts
+init_version();
 init_api_client();
 init_config();
+import { homedir as homedir3, platform } from "os";
 var HOME = homedir3();
 var REPORT_TIMEOUT_MS = 3e3;
 function classifyError(err) {
@@ -8494,9 +9305,9 @@ async function reportError(kind, err) {
       ...code ? { error_code: code } : {},
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     });
-    const base = process.env["MEMGINEERING_TELEMETRY_URL"]?.trim() || apiUrl();
+    const base2 = process.env["MEMGINEERING_TELEMETRY_URL"]?.trim() || apiUrl();
     await Promise.race([
-      fetch(`${base.replace(/\/+$/, "")}/v1/telemetry/error`, {
+      fetch(`${base2.replace(/\/+$/, "")}/v1/telemetry/error`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify(payload)
@@ -10587,10 +11398,10 @@ function adaptRegistryError(err) {
   }
   if (err instanceof KordisApiError) {
     const code = CODE_MAP[err.code] ?? "server_refused";
-    const base = err.hint ?? FALLBACK_HINTS[code] ?? "Nothing was changed. The registry refused this request; running it again is reasonable.";
+    const base2 = err.hint ?? FALLBACK_HINTS[code] ?? "Nothing was changed. The registry refused this request; running it again is reasonable.";
     const retry = err.retryAfter !== void 0 ? `
 Wait ${err.retryAfter}s before trying again.` : "";
-    return memgError(code, err.message, `${withFlags(base, err)}${retry}`);
+    return memgError(code, err.message, `${withFlags(base2, err)}${retry}`);
   }
   return null;
 }
@@ -10743,7 +11554,24 @@ var OpVerbSchema = z23.enum([
    * same thing. A verb the server can emit and this cannot name is a line this
    * CLI would silently count as corruption.
    */
-  "write"
+  "write",
+  /**
+   * Where a memory binds, moved — and nothing it says changed.
+   *
+   * Its own verb rather than a `revise` for the reason `reclassify` has one: a
+   * ledger is read by people asking what happened to their notes, and "revise"
+   * for a change that touched no conclusion tells them something untrue. This
+   * one has a second reason — a rescope is the only claimless write that can
+   * change WHICH decisions an agent is handed before it edits a file, so it is
+   * the row somebody goes looking for after a rule started or stopped applying
+   * to them.
+   *
+   * Note `unbind` is absent here on purpose: local `revise --no-rule` records
+   * `revise`, because it IS that command. These two are their own commands.
+   */
+  "rescope",
+  /** A memory was given an end date. It was NOT retired — see `expire`. */
+  "expire"
 ]);
 var OpRecordSchema = z23.object({
   op_id: z23.string().min(1),
@@ -10980,9 +11808,9 @@ async function namedCloudTarget(opts) {
       "`--brain <name>` reads an existing brain on the account. `--local` and `--vault <path>` read a folder on this machine. Nothing was read or changed; choose one target kind."
     );
   }
-  const base = apiUrl();
-  const credentials = await requireCredentials(base);
-  const brains = await listCloudBrains(credentials.token, base);
+  const base2 = apiUrl();
+  const credentials = await requireCredentials(base2);
+  const brains = await listCloudBrains(credentials.token, base2);
   if (brains.length === 0) {
     throw memgError(
       "invalid_input",
@@ -11001,23 +11829,23 @@ ${available}
 Use one of those names or ids. No brain was created.`
     );
   }
-  return { kind: "cloud", brainId: found.id, name: found.name, apiUrl: base };
+  return { kind: "cloud", brainId: found.id, name: found.name, apiUrl: base2 };
 }
 var isNoVaultLinked = (err) => typeof err === "object" && err !== null && err.code === "no_vault_linked";
 async function accountAwareRefusal() {
   try {
-    const base = apiUrl();
+    const base2 = apiUrl();
     const credentials = await readCredentials();
-    if (!credentials || credentials.api_url !== base) {
+    if (!credentials || credentials.api_url !== base2) {
       const cloud = (await loadConfig()).brain.cloud;
-      if (!cloud || cloud.api_url !== base) return null;
+      if (!cloud || cloud.api_url !== base2) return null;
       return memgError(
         "not_signed_in",
         `this machine is signed out of \`${oneLine(cloud.name, WIDTH.title)}\``,
         "Your notes are on that account \u2014 nothing is lost, and nothing here needs creating.\n\nSign back in:  `memgineering login`\n\nDo NOT run `init` or `link` to fix this. They make a NEW empty brain on this\nmachine and leave the notes where they are."
       );
     }
-    const brains = await listCloudBrains(credentials.token, base, { retries: 0 });
+    const brains = await listCloudBrains(credentials.token, base2, { retries: 0 });
     if (brains.length === 0) return null;
     const names = brains.map((b) => `  ${oneLine(b.name, WIDTH.title)}`).join("\n");
     return memgError(
@@ -11052,29 +11880,29 @@ machine and leave the notes where they are.`
   }
 }
 async function hostedPointer() {
-  const base = apiUrl();
+  const base2 = apiUrl();
   const config = await loadConfig();
   const cloud = config.brain.cloud;
-  if (!cloud || cloud.api_url !== base) return null;
+  if (!cloud || cloud.api_url !== base2) return null;
   const stored = await readCredentials().catch(() => null);
-  const signedIn = stored !== null && stored.api_url === base;
+  const signedIn = stored !== null && stored.api_url === base2;
   const pending = signedIn ? null : await readPendingLogin().catch(() => null);
   return {
     name: cloud.name,
     id: cloud.id,
-    apiUrl: base,
+    apiUrl: base2,
     signedIn,
-    signInPending: pending !== null && pending.api_url === base && !pendingExpired(pending)
+    signInPending: pending !== null && pending.api_url === base2 && !pendingExpired(pending)
   };
 }
 async function cloudTarget() {
-  const base = apiUrl();
+  const base2 = apiUrl();
   const config = await loadConfig();
   const cloud = config.brain.cloud;
-  if (!cloud || cloud.api_url !== base) return null;
-  const credentials = await currentCredentials(base);
+  if (!cloud || cloud.api_url !== base2) return null;
+  const credentials = await currentCredentials(base2);
   if (!credentials) return null;
-  return { kind: "cloud", brainId: cloud.id, name: cloud.name, apiUrl: base };
+  return { kind: "cloud", brainId: cloud.id, name: cloud.name, apiUrl: base2 };
 }
 
 // src/commands/base-write.ts
@@ -11979,6 +12807,7 @@ async function readEventsAt(stateDir) {
 init_index_build();
 
 // src/lib/base-files.ts
+init_src();
 init_init();
 var BASE_FILES = [
   {
@@ -12028,43 +12857,31 @@ var BASE_FILES = [
   }
 ];
 var HUB_PATH = "00_HUB/HUB.md";
+var TEMPLATE_SLOTS = 2;
+function capTemplates(cards, isTemplate) {
+  const kept = [];
+  const withheld = [];
+  let templates = 0;
+  for (const card of cards) {
+    if (isTemplate(card) && ++templates > TEMPLATE_SLOTS) withheld.push(card);
+    else kept.push(card);
+  }
+  return { kept, withheld };
+}
 function bodyOf2(content) {
   const stripped = content.replace(/^/, "");
   const fence2 = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(\r?\n|$)/.exec(stripped);
   return (fence2 ? stripped.slice(fence2[0].length) : stripped).trim();
 }
-var RETIRED_BASE_TEMPLATES = {
-  // Retired 0.11.1, when the prompt grew a storage-boundary invitation.
-  "01_BASE/BOUNDARIES.md": [
-    [
-      "---",
-      "memgineering:",
-      "  id: boundaries",
-      "  title: Boundaries",
-      "  summary: What an agent must not do without asking me first.",
-      "  scope: base",
-      "---",
-      "",
-      "# Boundaries",
-      "",
-      "Privacy, spending, anything irreversible, anything that leaves this",
-      "machine. Be specific \u2014 a boundary that has to be interpreted is one",
-      "that will be interpreted generously.",
-      "",
-      "- ",
-      ""
-    ].join("\n")
-  ]
-};
 function templatesFor(path, current) {
-  const retired = RETIRED_BASE_TEMPLATES[path] ?? [];
+  const retired = ownEntry(RETIRED_BASE_TEMPLATES, path) ?? [];
   return current === void 0 ? retired : [current, ...retired];
 }
 function isBaseFilePath(path) {
   return path.startsWith("01_BASE/");
 }
 function bodyStillTemplate(path, content) {
-  const template = files("brain")[path];
+  const template = ownEntry(files("brain"), path);
   if (template === void 0) return false;
   const body = bodyOf2(content);
   if (body === "") return false;
@@ -12090,7 +12907,7 @@ async function untouchedBase(adapter, paths) {
   const out = /* @__PURE__ */ new Set();
   await Promise.all(
     paths.map(async (path) => {
-      const template = templates[path];
+      const template = ownEntry(templates, path);
       if (template === void 0) return;
       const actual = await adapter.read(path).then((r) => r.content).catch(() => null);
       if (actual === null) return;
@@ -12173,6 +12990,9 @@ function openCommand() {
             claims: found.claims,
             relations: found.relations,
             ...showBody ? { body: found.body } : {},
+            // Only when the server said; an older one cannot, and false
+            // would be a claim it never made.
+            ...found.unfilled === void 0 ? {} : { scaffolding: found.unfilled },
             brain: { hosted: true, name: target.name }
           },
           human: () => {
@@ -12180,6 +13000,11 @@ function openCommand() {
               `## ${oneLine(String(found.memory["title"] ?? found.path), WIDTH.title)}
 `
             );
+            if (found.unfilled === true) {
+              printHuman(
+                c.yellow("not filled in yet") + c.gray(" \u2014 still the template it started as")
+              );
+            }
             const summary = found.memory["summary"];
             if (typeof summary === "string" && summary !== "") {
               printHuman(`> ${oneLine(summary, WIDTH.text)}
@@ -12784,7 +13609,7 @@ function rememberCommand() {
       const kind = parseKind(opts.kind);
       const neverStore = parseNeverStore(opts.neverStore);
       const binding = opts.rule === true || neverStore.length > 0;
-      const scope = await scopeToWrite(opts.scope);
+      const { scope, via: scopeVia } = await scopeToWrite(opts.scope);
       if (binding && scope === void 0 && !said.noScope) {
         throw memgError(
           "invalid_input",
@@ -12817,6 +13642,7 @@ function rememberCommand() {
             path: written.path,
             op_id: written.op_id,
             scope: written.scope,
+            scope_via: scopeVia,
             brain: { hosted: true, name: target.name },
             ...binding ? { binding: true } : {},
             ...neverStore.length > 0 ? { never_store: neverStore } : {},
@@ -12857,6 +13683,7 @@ function rememberCommand() {
             printHuman(
               `note:  \`${oneLine(written.id, WIDTH.handle)}\`  \xB7  \`${oneLine(written.path, WIDTH.path)}\``
             );
+            printHuman(c.gray(scopeLine(written.scope, scopeVia, binding)));
             if (binding) {
               printHuman("rule:  shown before you write a file here, once a session");
             }
@@ -12979,6 +13806,7 @@ function rememberCommand() {
           path,
           op_id: record.op_id,
           scope: scope ?? null,
+          scope_via: scopeVia,
           binding,
           ...neverStore.length > 0 ? { never_store: neverStore } : {},
           // Null on nearly every write, and present exactly when the ledger
@@ -12992,6 +13820,7 @@ function rememberCommand() {
 ` : `Remembered.
 `);
           printHuman(`note:  \`${id}\`  \xB7  \`${path}\``);
+          printHuman(c.gray(scopeLine(scope, scopeVia, binding)));
           if (binding) {
             printHuman(c.gray(`rule:  shown before you write a file here, once a session`));
           }
@@ -13039,14 +13868,27 @@ function renderObservation(args) {
   return lines2.join("\n");
 }
 async function scopeToWrite(flag2) {
-  if (flag2 === false) return void 0;
-  if (flag2 !== void 0) return flag2;
+  if (flag2 === false) return { scope: void 0, via: "flag" };
+  if (flag2 !== void 0) return { scope: flag2, via: "flag" };
   try {
-    const derived = (await projectOf()).name;
-    return derived !== null && stampable(derived) ? derived : void 0;
+    const derived = await projectOf();
+    return derived.name !== null && stampable(derived.name) ? { scope: derived.name, via: derived.via } : { scope: void 0, via: "none" };
   } catch {
-    return void 0;
+    return { scope: void 0, via: "none" };
+  }
+}
+function scopeLine(scope, via, binding) {
+  if (!scope) {
+    return binding ? "scope: none \u2014 this rule holds in every project" : "scope: none \u2014 recall finds it from any project";
   }
+  const from = {
+    flag: "as given with --scope",
+    override: "the name set for this folder (`memgineering project`)",
+    remote: "from this repository's git remote",
+    dirname: "from this folder's name \u2014 the repository has no git remote",
+    none: "as given"
+  };
+  return `scope: \`${oneLine(scope, WIDTH.title)}\` \u2014 ${from[via]}`;
 }
 function stampable(name) {
   if (name.length > SCOPE_LIMIT) return false;
@@ -14512,11 +15354,11 @@ init_init();
 var USER_PATH = "01_BASE/USER.md";
 var PREFERENCES_PATH = "01_BASE/PREFERENCES.md";
 var SCAFFOLD_PATHS = Object.keys(files("any"));
-function baseFilledPaths(base) {
-  return Object.keys(bulletsFor(base));
+function baseFilledPaths(base2) {
+  return Object.keys(bulletsFor(base2));
 }
-function scaffoldNotes(name, base = {}) {
-  const bullets = bulletsFor(base);
+function scaffoldNotes(name, base2 = {}) {
+  const bullets = bulletsFor(base2);
   return Object.entries(files(name)).map(([path, content]) => {
     const lines2 = bullets[path];
     return { path, content: lines2 ? fillPlaceholder(content, lines2) : content };
@@ -14526,10 +15368,10 @@ function oneLine2(value) {
   const trimmed = value?.replace(/\s+/g, " ").trim();
   return trimmed ? trimmed : void 0;
 }
-function bulletsFor(base) {
-  const user = oneLine2(base.user);
-  const language = oneLine2(base.language);
-  const about = oneLine2(base.about);
+function bulletsFor(base2) {
+  const user = oneLine2(base2.user);
+  const language = oneLine2(base2.language);
+  const about = oneLine2(base2.about);
   const out = {};
   const userBullets = [
     ...user === void 0 ? [] : [`Call them: ${user}`],
@@ -14580,9 +15422,9 @@ function createCommand() {
         "Nothing was created. Agree one with the user \u2014 it is what they will see in\n`memgineering brains` and how they tell two brains apart \u2014 then run\n`memgineering create <name>`."
       );
     }
-    const base = { user: opts.user, language: opts.language, about: opts.about };
-    const notes = scaffoldNotes(name, base);
-    const filled = baseFilledPaths(base);
+    const base2 = { user: opts.user, language: opts.language, about: opts.about };
+    const notes = scaffoldNotes(name, base2);
+    const filled = baseFilledPaths(base2);
     if (opts.dryRun === true) {
       printDual({
         json: {
@@ -15208,9 +16050,9 @@ function assertNothingLost(before, after, action) {
     });
   }
 }
-async function commit2(root, base, next) {
+async function commit2(root, base2, next) {
   const current = await readIgnoreFileState(root);
-  if (current.hash !== base.hash) {
+  if (current.hash !== base2.hash) {
     return { ok: false, reason: "revision_conflict", current };
   }
   if (next === current.content) return { ok: true, content: next, changed: false };
@@ -15256,15 +16098,15 @@ function planRemoveIgnoreEntry(content, relPath) {
   assertNothingLost(next, content, "un-excluding");
   return { content: next, changed: true };
 }
-async function addIgnoreEntry(root, relPath, base) {
-  const edit = planAddIgnoreEntry(base.content, relPath);
-  if (!edit.changed) return { ok: true, content: base.content, changed: false };
-  return commit2(root, base, edit.content);
+async function addIgnoreEntry(root, relPath, base2) {
+  const edit = planAddIgnoreEntry(base2.content, relPath);
+  if (!edit.changed) return { ok: true, content: base2.content, changed: false };
+  return commit2(root, base2, edit.content);
 }
-async function removeIgnoreEntry(root, relPath, base) {
-  const edit = planRemoveIgnoreEntry(base.content, relPath);
-  if (!edit.changed) return { ok: true, content: base.content, changed: false };
-  return commit2(root, base, edit.content);
+async function removeIgnoreEntry(root, relPath, base2) {
+  const edit = planRemoveIgnoreEntry(base2.content, relPath);
+  if (!edit.changed) return { ok: true, content: base2.content, changed: false };
+  return commit2(root, base2, edit.content);
 }
 
 // src/commands/curation.ts
@@ -15379,9 +16221,9 @@ function ignoreCommand(mode) {
       createPrefix: brain.observationsDir
     });
     const target = mode === "exclude" ? await mustMatchAFile(brain.root, adapter, path) : path;
-    const base = await readIgnoreFileState(brain.root);
+    const base2 = await readIgnoreFileState(brain.root);
     const record = await withWriteLock(brain.root, async () => {
-      const result = mode === "exclude" ? await addIgnoreEntry(brain.root, target, base) : await removeIgnoreEntry(brain.root, target, base);
+      const result = mode === "exclude" ? await addIgnoreEntry(brain.root, target, base2) : await removeIgnoreEntry(brain.root, target, base2);
       if (!result.ok) {
         throw memgError(
           "undo_conflict",
@@ -15394,11 +16236,11 @@ function ignoreCommand(mode) {
         verb: mode,
         target: ".memgignore",
         memoryId: null,
-        hashBefore: hashContent(base.content),
+        hashBefore: hashContent(base2.content),
         hashAfter: hashContent(result.content),
-        patch: { before: base.content, after: result.content },
+        patch: { before: base2.content, after: result.content },
         rationale,
-        snapshotBefore: base.content
+        snapshotBefore: base2.content
       });
     });
     printDual({
@@ -15502,59 +16344,321 @@ var unretireCommand = () => lifecycleCommand("unretire");
 var excludeCommand = () => ignoreCommand("exclude");
 var unexcludeCommand = () => ignoreCommand("unexclude");
 
-// src/commands/evidence.ts
+// src/commands/scope-validity.ts
 init_src();
 import { Command as Command15 } from "commander";
+init_errors();
 init_index_build();
 init_cloud_brain();
 init_vault();
 init_ui();
-function evidenceCommand() {
-  return new Command15("evidence").description("how much a memory has been used, and why it last changed").argument("<ref>", "handle, id, path, or exact title").option("--vault <path>", "which brain to read").option("--local", "read the brain on this machine, even when signed in to a hosted one").option(
-    "--brain <name>",
-    "read from one existing hosted brain by name or id, without changing the pointer"
-  ).action(async (ref, opts) => {
-    const target = await resolveTarget({
-      ...opts.brain === void 0 ? {} : { brain: opts.brain },
-      ...opts.local === void 0 ? {} : { local: opts.local },
-      ...opts.vault === void 0 ? {} : { vault: opts.vault }
-    });
-    if (target.kind === "cloud") {
-      const cloud = await openCloudBrain(target);
-      const report4 = await cloudEvidence(cloud, ref);
+function rescopeCommand() {
+  return new Command15("rescope").description("change which project a memory binds in \u2014 nothing it says changes").argument("<ref>", "handle, id, path, or exact title").option("--scope <name>", "the project it binds in from now on").option("--global", "it binds everywhere \u2014 say this rather than leaving the scope off").option("--reason <text>", "why \u2014 kept in the ledger").option("--vault <path>", "which brain the memory is in").option("--local", "use the brain on this machine, even when signed in to a hosted one").action(
+    async (ref, opts) => {
+      const scope = scopeAskedFor(opts);
+      const where = await resolveTarget({
+        ...opts.local === void 0 ? {} : { local: opts.local },
+        ...opts.vault === void 0 ? {} : { vault: opts.vault }
+      });
+      if (where.kind === "cloud") {
+        await rescopeHosted(where, ref, scope, opts.reason);
+        return;
+      }
+      const { entry, record, was } = await rescopeLocal(opts.vault, ref, scope, opts.reason);
+      const widened = isGlobalScope(scope);
       printDual({
-        json: { ...report4, brain: { hosted: true, name: target.name } },
-        human: () => renderEvidence(viewFromCloud(report4), {
-          now: /* @__PURE__ */ new Date(),
-          hosted: true,
-          brain: target.name
-        })
+        json: {
+          action: "rescope",
+          memory_id: entry.memory.id,
+          target: entry.path,
+          scope: widened ? null : scope,
+          op_id: record.op_id
+        },
+        human: () => {
+          printHuman(
+            widened ? `**${oneLine(entry.memory.title, WIDTH.title)}** now binds everywhere.
+` : `**${oneLine(entry.memory.title, WIDTH.title)}** now binds in **${oneLine(scope, WIDTH.title)}**.
+`
+          );
+          printHuman(c.gray(reachOf(entry.memory.binding === true, widened, scope, was)));
+          printHuman(c.gray(`
+Undo: \`${undoHint(record.op_id, opts)}\``));
+        }
       });
-      return;
     }
-    const brain = target.brain;
-    const adapter = await openBrainOrExplain(brain.root);
-    const built = await openIndex(adapter, brain.root);
-    const entry = resolveRef(built.entries, ref);
-    const [events, ledger] = await Promise.all([readEvents(brain.root), readOps(brain.root)]);
-    const now = /* @__PURE__ */ new Date();
-    const report3 = assembleEvidence(entry, events, ledger.ops, {
-      contextDir: process.cwd(),
-      now,
-      brain: built.entries
-    });
-    printDual({
-      json: report3,
-      human: () => renderEvidence(report3, { now, hosted: false })
-    });
-  });
+  );
 }
-function renderEvidence(report3, opts) {
-  const brainHeading = opts.brain === void 0 ? "" : ` \u2014 ${oneLine(opts.brain, WIDTH.title)}`;
-  printHuman(`## evidence: ${oneLine(report3.title, WIDTH.title)}${brainHeading}
-`);
-  printHuman(
-    `\`id: ${oneLine(report3.id, WIDTH.handle)}\`  \xB7  \`${oneLine(report3.path, WIDTH.path)}\`
+function expireCommand() {
+  return new Command15("expire").description("give a memory an end date \u2014 it is NOT retired, and recall still returns it").argument("<ref>", "handle, id, path, or exact title").requiredOption("--until <date>", "the day it stops being current, e.g. 2026-10-31").option("--reason <text>", "why \u2014 kept in the ledger").option("--vault <path>", "which brain the memory is in").option("--local", "use the brain on this machine, even when signed in to a hosted one").action(
+    async (ref, opts) => {
+      const where = await resolveTarget({
+        ...opts.local === void 0 ? {} : { local: opts.local },
+        ...opts.vault === void 0 ? {} : { vault: opts.vault }
+      });
+      if (where.kind === "cloud") {
+        await expireHosted(where, ref, opts.until, opts.reason);
+        return;
+      }
+      const { entry, record } = await expireLocal(opts.vault, ref, opts.until, opts.reason);
+      printDual({
+        json: {
+          action: "expire",
+          memory_id: entry.memory.id,
+          target: entry.path,
+          valid_until: opts.until.trim(),
+          op_id: record.op_id
+        },
+        human: () => {
+          printHuman(
+            `**${oneLine(entry.memory.title, WIDTH.title)}** holds until **${oneLine(opts.until.trim(), WIDTH.title)}**.
+`
+          );
+          printHuman(
+            c.gray(
+              "It is NOT retired. After that date recall still returns it \u2014 ranked below what is current, and labelled.\nTo take it out of the answers: `memgineering retire " + oneLine(entry.path, WIDTH.path) + "`"
+            )
+          );
+          printHuman(c.gray(`
+Undo: \`${undoHint(record.op_id, opts)}\``));
+        }
+      });
+    }
+  );
+}
+function scopeAskedFor(opts) {
+  const named = opts.scope !== void 0;
+  if (named && opts.global === true) {
+    throw memgError(
+      "invalid_input",
+      "`--scope` and `--global` say opposite things",
+      "Pass one. `--scope <name>` binds the memory in that project; `--global` binds it everywhere."
+    );
+  }
+  if (opts.global === true) return GLOBAL_SCOPE;
+  if (!named || oneLineWhole(opts.scope ?? "") === "") {
+    throw memgError(
+      "invalid_input",
+      "rescope needs to know where the memory binds",
+      "Pass `--scope <project>`, or `--global` if it holds everywhere. Widening is spelled out because it is the change that is hardest to notice afterwards."
+    );
+  }
+  const scope = oneLineWhole(opts.scope ?? "");
+  if (isGlobalScope(scope)) {
+    throw memgError(
+      "invalid_input",
+      "`global` is a reserved scope",
+      "Use `--global` to say a memory binds everywhere. Keeping one spelling of it means nothing downstream has two to match on."
+    );
+  }
+  return scope;
+}
+function reachOf(binding, widened, scope, was) {
+  if (!binding) {
+    return "Where a memory is scoped decides which project raises it. Nothing else about it changed.";
+  }
+  if (widened) {
+    return `It is a rule, and it binds everywhere now${was === null ? "" : ` rather than only in ${was}`}. Agents in every project will be shown it before they edit a file.`;
+  }
+  return `It is a rule, and it binds only in ${scope} now. Agents working anywhere else will no longer be shown it.`;
+}
+async function rescopeLocal(vault, ref, scope, reason) {
+  const { adapter, brain, built, entry } = await openFor(vault, ref);
+  assertLocalBoundary(built.entries, { texts: [scope] });
+  const was = declaredScopeOf(entry.memory);
+  if (isGlobalScope(scope) ? was === null : was === scope) {
+    throw memgError(
+      "nothing_to_change",
+      `${entry.memory.title} already binds there`,
+      `Nothing was written, and nothing needed to be. \`memgineering open ${ref}\` shows the scope it declares; a note that declares none binds everywhere.`
+    );
+  }
+  const record = await write(
+    adapter,
+    brain.root,
+    entry,
+    ref,
+    "rescope",
+    () => rescopeInput(entry, scope, { reason: reason ?? null }),
+    reason
+  );
+  return { entry, record, was };
+}
+async function expireLocal(vault, ref, until, reason) {
+  const { adapter, brain, entry } = await openFor(vault, ref);
+  const wanted = until.trim();
+  if (!Number.isFinite(Date.parse(wanted))) {
+    throw memgError(
+      "invalid_input",
+      `${until} is not a date`,
+      "Pass an ISO date, such as 2026-10-31 or 2026-10-31T00:00:00Z."
+    );
+  }
+  if ((entry.claims[0]?.valid_until ?? entry.memory.valid_until ?? null) === wanted) {
+    throw memgError(
+      "nothing_to_change",
+      `${entry.memory.title} already ends then`,
+      `Nothing was written, and nothing needed to be. \`memgineering open ${ref}\` shows the date it carries.`
+    );
+  }
+  const record = await write(
+    adapter,
+    brain.root,
+    entry,
+    ref,
+    "expire",
+    () => expireInput(entry, wanted, { reason: reason ?? null }),
+    reason
+  );
+  return { entry, record };
+}
+async function openFor(vault, ref) {
+  const { brain } = await resolveBrain(vault);
+  const adapter = await LocalFileCasAdapter.openVault(brain.root, {
+    createPrefix: brain.observationsDir
+  });
+  const built = await openIndex(adapter, brain.root);
+  return { adapter, brain, built, entry: resolveRef(built.entries, ref) };
+}
+async function write(adapter, root, entry, ref, verb, input, reason) {
+  const rationale = sanitizeRationale(reason);
+  const result = commit(asSingleMatch(entry), input());
+  if (result.action === "ignore") {
+    throw memgError("invalid_input", `${verb} produced nothing`, "This is a defect \u2014 report it.");
+  }
+  const preview = await previewProposal(adapter, result.proposal);
+  if (preview.refusal) throw preview.refusal;
+  const before = await adapter.read(entry.path);
+  if (changesNothing(result.proposal, preview, before.content)) {
+    throw memgError(
+      "nothing_to_change",
+      `${entry.path} already says exactly this`,
+      `Nothing was written. \`memgineering open ${ref}\` shows what it says now.`
+    );
+  }
+  return withWriteLock(root, async () => {
+    const outcome = await applyProposal(
+      adapter,
+      approve(result.proposal, {
+        actor: "agent",
+        note: `${verb}d autonomously; reversible from the operation ledger`
+      })
+    );
+    if (!outcome.ok) {
+      throw memgError(
+        "undo_conflict",
+        `${entry.path} changed while this was being prepared`,
+        "Run the command again \u2014 it will re-read the note first."
+      );
+    }
+    return appendOp(root, {
+      verb,
+      target: entry.path,
+      memoryId: entry.memory.id,
+      hashBefore: hashContent(before.content),
+      hashAfter: hashContent(outcome.content),
+      patch: { before: preview.before, after: preview.after },
+      rationale,
+      snapshotBefore: before.content
+    });
+  });
+}
+async function rescopeHosted(where, ref, scope, reason) {
+  const brain = await openCloudBrain(where);
+  const result = await cloudRescope(brain, {
+    ref,
+    scope,
+    ...reason === void 0 ? {} : { reason }
+  });
+  printDual({
+    json: { brain: where.name, ...result },
+    human: () => {
+      printHuman(
+        result.scope === null ? `Binds everywhere in **${oneLine(where.name, WIDTH.title)}**.
+` : `Binds in **${oneLine(result.scope, WIDTH.title)}**.
+`
+      );
+      printHuman(`\`${oneLine(result.target, WIDTH.path)}\`
+`);
+      printHuman(c.gray(oneLine(result.note, WIDTH.text)));
+      printHuman(c.gray(`
+Undo: \`memgineering undo ${result.op_id}\``));
+    }
+  });
+}
+async function expireHosted(where, ref, until, reason) {
+  const brain = await openCloudBrain(where);
+  const result = await cloudExpire(brain, {
+    ref,
+    until,
+    ...reason === void 0 ? {} : { reason }
+  });
+  printDual({
+    json: { brain: where.name, ...result },
+    human: () => {
+      printHuman(`Holds until **${oneLine(result.valid_until, WIDTH.title)}**.
+`);
+      printHuman(`\`${oneLine(result.target, WIDTH.path)}\`
+`);
+      printHuman(c.gray(oneLine(result.note, WIDTH.text)));
+      printHuman(c.gray(`
+Undo: \`memgineering undo ${result.op_id}\``));
+    }
+  });
+}
+
+// src/commands/evidence.ts
+init_src();
+import { Command as Command16 } from "commander";
+init_index_build();
+init_cloud_brain();
+init_vault();
+init_ui();
+function evidenceCommand() {
+  return new Command16("evidence").description("how much a memory has been used, and why it last changed").argument("<ref>", "handle, id, path, or exact title").option("--vault <path>", "which brain to read").option("--local", "read the brain on this machine, even when signed in to a hosted one").option(
+    "--brain <name>",
+    "read from one existing hosted brain by name or id, without changing the pointer"
+  ).action(async (ref, opts) => {
+    const target = await resolveTarget({
+      ...opts.brain === void 0 ? {} : { brain: opts.brain },
+      ...opts.local === void 0 ? {} : { local: opts.local },
+      ...opts.vault === void 0 ? {} : { vault: opts.vault }
+    });
+    if (target.kind === "cloud") {
+      const cloud = await openCloudBrain(target);
+      const report4 = await cloudEvidence(cloud, ref);
+      printDual({
+        json: { ...report4, brain: { hosted: true, name: target.name } },
+        human: () => renderEvidence(viewFromCloud(report4), {
+          now: /* @__PURE__ */ new Date(),
+          hosted: true,
+          brain: target.name
+        })
+      });
+      return;
+    }
+    const brain = target.brain;
+    const adapter = await openBrainOrExplain(brain.root);
+    const built = await openIndex(adapter, brain.root);
+    const entry = resolveRef(built.entries, ref);
+    const [events, ledger] = await Promise.all([readEvents(brain.root), readOps(brain.root)]);
+    const now = /* @__PURE__ */ new Date();
+    const report3 = assembleEvidence(entry, events, ledger.ops, {
+      contextDir: process.cwd(),
+      now,
+      brain: built.entries
+    });
+    printDual({
+      json: report3,
+      human: () => renderEvidence(report3, { now, hosted: false })
+    });
+  });
+}
+function renderEvidence(report3, opts) {
+  const brainHeading = opts.brain === void 0 ? "" : ` \u2014 ${oneLine(opts.brain, WIDTH.title)}`;
+  printHuman(`## evidence: ${oneLine(report3.title, WIDTH.title)}${brainHeading}
+`);
+  printHuman(
+    `\`id: ${oneLine(report3.id, WIDTH.handle)}\`  \xB7  \`${oneLine(report3.path, WIDTH.path)}\`
 `
   );
   if (report3.critical) {
@@ -15801,7 +16905,7 @@ init_config();
 import { createHash as createHash7 } from "crypto";
 import { mkdir as mkdir11, readdir as readdir6, stat as stat4, unlink as unlink3, writeFile as writeFile9 } from "fs/promises";
 import { dirname as dirname5, isAbsolute as isAbsolute3, join as join18, resolve as resolve9 } from "path";
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
 
 // src/lib/rules.ts
 init_src();
@@ -15872,7 +16976,7 @@ init_src();
 init_deadline();
 init_cloud_brain();
 function guardCommand() {
-  return new Command16("guard").description("hook entry \u2014 show the user\u2019s rules before the first edit of a session").option("--context-dir <path>", "where the work is happening, when stdin does not say").option("--at <event>", "pre-tool-use | stop", "pre-tool-use").action(async (opts) => {
+  return new Command17("guard").description("hook entry \u2014 show the user\u2019s rules before the first edit of a session").option("--context-dir <path>", "where the work is happening, when stdin does not say").option("--at <event>", "pre-tool-use | stop", "pre-tool-use").action(async (opts) => {
     try {
       const out = await withDeadline(HOOK_DEADLINE_MS, async () => {
         const payload = await readPayload();
@@ -16068,7 +17172,11 @@ async function hostedRuleLines(where, contextDir) {
 }
 function groupHostedLines(rules, project) {
   const width = ruleWidthFor(rules.length);
-  const line = (r) => renderRuleLine(r.text ?? r.summary ?? r.title, width);
+  const line = (r) => {
+    const quoted = renderRuleLine(r.text ?? r.summary ?? r.title, width);
+    return r.freshness === "current" || r.freshness === void 0 ? quoted : `${quoted}
+  (${r.freshness === "expired" ? "past its end date" : "superseded"} \u2014 worth checking)`;
+  };
   const globals = rules.filter((r) => r.lane === "global");
   const scoped = rules.filter((r) => r.lane === "project");
   if (globals.length === 0 || scoped.length === 0) return rules.map(line);
@@ -16089,14 +17197,14 @@ init_link();
 init_src();
 init_walk();
 import { lstat as lstat4, readFile as readFile19 } from "fs/promises";
-import { Command as Command18 } from "commander";
+import { Command as Command19 } from "commander";
 init_errors();
 init_cloud_brain();
 
 // src/commands/retract.ts
 init_errors();
 init_cloud_brain();
-import { Command as Command17 } from "commander";
+import { Command as Command18 } from "commander";
 init_vault();
 init_ui();
 var CONTENT_VERBS = /* @__PURE__ */ new Set([
@@ -16167,7 +17275,7 @@ function parseInstant(flag2, raw) {
   return { ms, iso: new Date(ms).toISOString() };
 }
 function retractCommand() {
-  return new Command17("retract").description(
+  return new Command18("retract").description(
     "retire every memory one writer or one stretch of time wrote \u2014 shows the set first; --yes applies it"
   ).option("--actor <actor>", 'writes recorded under this actor, e.g. "mcp:ChatGPT" or "agent"').option(
     "--token <id>",
@@ -16382,7 +17490,7 @@ ${failed.length} could not be retired:`);
 init_vault();
 init_ui();
 function logCommand() {
-  return new Command18("log").description("what changed in this brain, and what can still be undone").option("--limit <n>", "how many operations", (v) => parseInt(v, 10), 20).option("--verbose", "include hashes and reverse patches").option("--vault <path>", "which brain to read").option("--local", "read the brain on this machine, even when signed in to a hosted one").option(
+  return new Command19("log").description("what changed in this brain, and what can still be undone").option("--limit <n>", "how many operations", (v) => parseInt(v, 10), 20).option("--verbose", "include hashes and reverse patches").option("--vault <path>", "which brain to read").option("--local", "read the brain on this machine, even when signed in to a hosted one").option(
     "--brain <name>",
     "read one existing hosted brain by name or id, without changing the pointer"
   ).option("--actor <actor>", 'only operations recorded under this actor, e.g. "mcp:ChatGPT" or "agent"').option("--token <id>", "only operations made with this token (id or 5+ char prefix) \u2014 hosted brains").option("--since <when>", "only operations at or after this date / ISO instant").option("--until <when>", "only operations before this date / ISO instant").action(async (opts) => {
@@ -16563,9 +17671,19 @@ var REVERSIBLE_LOCAL = /* @__PURE__ */ new Set([
   "retire",
   "unretire",
   "exclude",
-  "unexclude"
+  "unexclude",
+  "rescope",
+  "expire"
+]);
+var REVERSIBLE_HOSTED = /* @__PURE__ */ new Set([
+  "remember",
+  "revise",
+  "retire",
+  "unretire",
+  "write",
+  "rescope",
+  "expire"
 ]);
-var REVERSIBLE_HOSTED = /* @__PURE__ */ new Set(["remember", "revise", "retire", "unretire", "write"]);
 function undoable(op, hosted) {
   if (op.undone || op.diverged || op.superseded) return false;
   return (hosted ? REVERSIBLE_HOSTED : REVERSIBLE_LOCAL).has(op.verb);
@@ -16650,10 +17768,10 @@ async function readOrNull(root, path) {
 // src/commands/project.ts
 init_errors();
 import { resolve as resolve10 } from "path";
-import { Command as Command19 } from "commander";
+import { Command as Command20 } from "commander";
 init_ui();
 function projectCommand() {
-  return new Command19("project").description("show or set what the work in this folder is called").argument("[name]", "what to call it \u2014 omit to show what this folder answers to").option("--here <dir>", "act on this directory instead of the current one").option("--unset", "forget the name set here and go back to what the repository says").addHelpText(
+  return new Command20("project").description("show or set what the work in this folder is called").argument("[name]", "what to call it \u2014 omit to show what this folder answers to").option("--here <dir>", "act on this directory instead of the current one").option("--unset", "forget the name set here and go back to what the repository says").addHelpText(
     "after",
     [
       "",
@@ -16780,18 +17898,18 @@ init_api_client();
 init_credentials();
 init_pending_login();
 init_ui();
-import { Command as Command21 } from "commander";
+import { Command as Command22 } from "commander";
 function logoutCommand() {
-  return new Command21("logout").description("sign out of your account \u2014 the pointer and your notes stay").option("--all", "revoke every token on the account, not just this machine\u2019s").option(
+  return new Command22("logout").description("sign out of your account \u2014 the pointer and your notes stay").option("--all", "revoke every token on the account, not just this machine\u2019s").option(
     "--local",
     "forget the token here without telling the server \u2014 only for a server you cannot reach"
   ).action(async (opts) => {
-    const base = apiUrl();
+    const base2 = apiUrl();
     const credentials = await readCredentials();
     await clearPendingLogin();
     if (!credentials) {
       printDual({
-        json: { signed_out: true, was_signed_in: false, api_url: base },
+        json: { signed_out: true, was_signed_in: false, api_url: base2 },
         human: () => printHuman("Not signed in \u2014 nothing to do.")
       });
       return;
@@ -16901,12 +18019,12 @@ async function revokeRegistrySession(reg) {
 
 // src/commands/onboard.ts
 init_src();
-import { Command as Command22 } from "commander";
+import { Command as Command23 } from "commander";
 init_cloud_brain();
 init_vault();
 init_ui();
 function onboardCommand() {
-  return new Command22("onboard").description("what to ask so the brain knows who it belongs to").option("--vault <path>", "which brain").option("--local", "use the brain on this machine, even when signed in to a hosted one").option(
+  return new Command23("onboard").description("what to ask so the brain knows who it belongs to").option("--vault <path>", "which brain").option("--local", "use the brain on this machine, even when signed in to a hosted one").option(
     "--brain <name>",
     "read one existing hosted brain by name or id, without changing the pointer"
   ).action(async (opts) => {
@@ -17052,9 +18170,9 @@ init_cloud_brain();
 init_ui();
 import { mkdir as mkdir12, readFile as readFile20, writeFile as writeFile10 } from "fs/promises";
 import { dirname as dirname6, isAbsolute as isAbsolute4, join as join19, resolve as resolve11, sep as sep2 } from "path";
-import { Command as Command23 } from "commander";
+import { Command as Command24 } from "commander";
 function pullCommand() {
-  return new Command23("pull").description("download your hosted brain to a folder on this machine").argument("[destination]", "folder to write into (created if missing)").option("--brain <name>", "which hosted brain to download").option("--dry-run", "say what would be written and write nothing").action(async (destination, opts) => {
+  return new Command24("pull").description("download your hosted brain to a folder on this machine").argument("[destination]", "folder to write into (created if missing)").option("--brain <name>", "which hosted brain to download").option("--dry-run", "say what would be written and write nothing").action(async (destination, opts) => {
     const { brain: source, others } = await resolveSource(opts.brain);
     const target = resolve11(destination ?? `./${oneLine(source.name, WIDTH.title)}`);
     const first = await cloudListNotes(source, { limit: 1 });
@@ -17181,9 +18299,9 @@ async function collectPaths(source) {
   return all;
 }
 async function resolveSource(named) {
-  const base = apiUrl();
-  const credentials = await requireCredentials(base);
-  const brains = await listCloudBrains(credentials.token, base);
+  const base2 = apiUrl();
+  const credentials = await requireCredentials(base2);
+  const brains = await listCloudBrains(credentials.token, base2);
   if (brains.length === 0) {
     throw memgError(
       "invalid_input",
@@ -17192,7 +18310,7 @@ async function resolveSource(named) {
     );
   }
   const pointedAt = named ? null : (await loadConfig()).brain.cloud;
-  const usable = pointedAt && pointedAt.api_url === base ? pointedAt.id : null;
+  const usable = pointedAt && pointedAt.api_url === base2 ? pointedAt.id : null;
   const found = named ? brains.find((b) => b.name === named || b.id === named) : usable ? brains.find((b) => b.id === usable) ?? (brains.length === 1 ? brains[0] : void 0) : brains.length === 1 ? brains[0] : void 0;
   if (!found) {
     throw memgError(
@@ -17202,7 +18320,7 @@ async function resolveSource(named) {
     );
   }
   return {
-    brain: { brainId: found.id, name: found.name, token: credentials.token, apiUrl: base },
+    brain: { brainId: found.id, name: found.name, token: credentials.token, apiUrl: base2 },
     // The ones this run is NOT downloading.
     //
     // A tester pulled a brain, was told 21 notes had arrived, and reasonably
@@ -17254,7 +18372,7 @@ async function exists(file) {
 }
 
 // src/commands/publish.ts
-import { Command as Command25 } from "commander";
+import { Command as Command26 } from "commander";
 import { z as z32 } from "zod";
 init_src();
 init_errors();
@@ -17398,6 +18516,7 @@ init_index_build();
 // src/lib/registry-session.ts
 init_errors();
 init_credentials();
+init_version();
 function registryApiUrl(stored) {
   const override = process.env["KORDIS_API_URL"];
   return override !== void 0 && override !== "" ? override : stored;
@@ -18150,7 +19269,7 @@ function isSameBrainNote(publishedOrigin, memoryId) {
 }
 
 // src/commands/registry/read.ts
-import { Command as Command24 } from "commander";
+import { Command as Command25 } from "commander";
 init_errors();
 init_credentials();
 
@@ -18171,8 +19290,9 @@ function untrustedFenceNotice(sentinel) {
 
 // src/commands/registry/read.ts
 init_ui();
+init_version();
 function readCommand() {
-  return new Command24("read").description("read a judgment from the public layer into your context (nothing is installed)").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--vault <path>", "which brain records that this was read").option("--local", "record it beside the brain on this machine, not the hosted one").addHelpText(
+  return new Command25("read").description("read a judgment from the public layer into your context (nothing is installed)").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--vault <path>", "which brain records that this was read").option("--local", "record it beside the brain on this machine, not the hosted one").addHelpText(
     "after",
     "\nEnvironment:\n  KORDIS_API_URL=<url>   read from this registry instead of the linked one\n"
   ).action(async (rawSlug, opts) => {
@@ -18320,7 +19440,7 @@ async function recordUsage(verb, detail, where = {}) {
 init_vault();
 init_ui();
 function publishCommand() {
-  return new Command25("publish").description("publish one decision from this brain to the public layer").argument("<ref>", "handle, id, path, or exact title of the note to publish").option("--slug <name>", "the package name (default: derived from the note title)").option("--yes", "actually send it (without this, nothing leaves this machine)").option("--reason <text>", "why this is being published \u2014 the user's own words").option("--no-lineage", "do not propose lineage from what this machine has adapted").option(
+  return new Command26("publish").description("publish one decision from this brain to the public layer").argument("<ref>", "handle, id, path, or exact title of the note to publish").option("--slug <name>", "the package name (default: derived from the note title)").option("--yes", "actually send it (without this, nothing leaves this machine)").option("--reason <text>", "why this is being published \u2014 the user's own words").option("--no-lineage", "do not propose lineage from what this machine has adapted").option(
     "--bump <kind>",
     "patch | minor | major \u2014 publish the next version of a package this note already produced"
   ).option("--wait <ms>", "how long to wait for the AI review before answering (default 3000)").option("--vault <path>", "which brain to read").option("--local", "read the brain on this machine, even when signed in to a hosted one").addHelpText(
@@ -18393,8 +19513,8 @@ function publishCommand() {
         });
         return;
       }
-      const session = await openRegistrySession();
       const waitForReviewMs = parseWait(opts.wait);
+      const session = await openRegistrySession();
       const response = await publishOrExplain(
         session.client,
         ref,
@@ -18646,7 +19766,7 @@ function parseWait(raw) {
 }
 
 // src/commands/registry/adapt.ts
-import { Command as Command26 } from "commander";
+import { Command as Command27 } from "commander";
 init_errors();
 
 // src/lib/harness-context.ts
@@ -18655,6 +19775,7 @@ import { access, readFile as readFile21 } from "fs/promises";
 import { join as join20 } from "path";
 var PER_FILE_CAP = 16 * 1024;
 var TOTAL_CAP = 48 * 1024;
+var TRUNCATION_RESERVE = 64;
 async function pathExists(p) {
   try {
     await access(p);
@@ -18665,6 +19786,7 @@ async function pathExists(p) {
 }
 function capContent(raw, cap) {
   if (Buffer.byteLength(raw, "utf8") <= cap) return { content: raw, truncated: false };
+  const fill = cap - TRUNCATION_RESERVE;
   const lines2 = raw.split("\n");
   let acc = 0;
   let lastHeadingIdx = -1;
@@ -18673,7 +19795,7 @@ function capContent(raw, cap) {
     const line = lines2[i] ?? "";
     const lineBytes = Buffer.byteLength(`${line}
 `, "utf8");
-    if (acc + lineBytes > cap) {
+    if (acc + lineBytes > fill) {
       cutIdx = i;
       break;
     }
@@ -18681,6 +19803,7 @@ function capContent(raw, cap) {
     if (/^#{1,6}\s/.test(line)) lastHeadingIdx = i;
   }
   const cut2 = lastHeadingIdx > cutIdx / 2 ? lastHeadingIdx : cutIdx;
+  if (cut2 === 0) return null;
   const kept = lines2.slice(0, cut2).join("\n");
   return {
     content: `${kept}
@@ -18705,7 +19828,6 @@ async function readHarnessContext(cwd = process.cwd(), home = agentHome()) {
   const files2 = [];
   let totalBytes = 0;
   for (const cand of candidates) {
-    if (totalBytes >= TOTAL_CAP) break;
     if (!await pathExists(cand.path)) continue;
     let raw;
     try {
@@ -18714,7 +19836,9 @@ async function readHarnessContext(cwd = process.cwd(), home = agentHome()) {
       continue;
     }
     const cap = Math.min(PER_FILE_CAP, TOTAL_CAP - totalBytes);
-    const { content, truncated } = capContent(raw, cap);
+    const capped2 = capContent(raw, cap);
+    if (capped2 === null) break;
+    const { content, truncated } = capped2;
     totalBytes += Buffer.byteLength(content, "utf8");
     files2.push({
       path: cand.display,
@@ -18778,7 +19902,7 @@ function renderBrief(res, harness) {
   return out.join("\n");
 }
 function adaptCommand() {
-  return new Command26("adapt").description("fit a public judgment to your existing harness (prints a brief; writes nothing)").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--vault <path>", "which brain records that this was adapted").option("--local", "record it beside the brain on this machine, not the hosted one").addHelpText(
+  return new Command27("adapt").description("fit a public judgment to your existing harness (prints a brief; writes nothing)").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--vault <path>", "which brain records that this was adapted").option("--local", "record it beside the brain on this machine, not the hosted one").addHelpText(
     "after",
     "\nEnvironment:\n  KORDIS_API_URL=<url>   read from this registry instead of the linked one\n"
   ).action(async (rawSlug, opts) => {
@@ -18826,10 +19950,10 @@ function adaptCommand() {
 }
 
 // src/commands/registry/info.ts
-import { Command as Command27 } from "commander";
+import { Command as Command28 } from "commander";
 init_ui();
 function infoCommand() {
-  return new Command27("info").description("what a package in the public layer is, without reading it").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").addHelpText(
+  return new Command28("info").description("what a package in the public layer is, without reading it").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").addHelpText(
     "after",
     "\nEnvironment:\n  KORDIS_API_URL=<url>   ask this registry instead of the linked one\n"
   ).action(async (rawSlug) => {
@@ -18915,7 +20039,7 @@ function renderCanonical(component) {
 }
 
 // src/commands/registry/search.ts
-import { Command as Command28 } from "commander";
+import { Command as Command29 } from "commander";
 init_errors();
 init_ui();
 var SEARCHABLE_TYPES = PHASE_1_TYPES;
@@ -18923,7 +20047,7 @@ var LIMIT_MIN = 1;
 var LIMIT_MAX = 100;
 var LIMIT_DEFAULT = 20;
 function searchCommand() {
-  return new Command28("search").description("find a judgment in the public layer (titles only; nothing is read or installed)").argument("[query...]", "words to match against title and description").option("--type <type>", `narrow by kind: ${SEARCHABLE_TYPES.join("|")}`).option("--limit <n>", `how many results (${LIMIT_MIN}-${LIMIT_MAX})`, String(LIMIT_DEFAULT)).addHelpText(
+  return new Command29("search").description("find a judgment in the public layer (titles only; nothing is read or installed)").argument("[query...]", "words to match against title and description").option("--type <type>", `narrow by kind: ${SEARCHABLE_TYPES.join("|")}`).option("--limit <n>", `how many results (${LIMIT_MIN}-${LIMIT_MAX})`, String(LIMIT_DEFAULT)).addHelpText(
     "after",
     "\nEnvironment:\n  KORDIS_API_URL=<url>   search this registry instead of the linked one\n"
   ).action(async (query, opts) => {
@@ -19101,7 +20225,7 @@ function parseLimit2(raw) {
 }
 
 // src/commands/registry/pull.ts
-import { Command as Command29 } from "commander";
+import { Command as Command30 } from "commander";
 import prompts3 from "prompts";
 import { existsSync, lstatSync, realpathSync } from "fs";
 import { mkdir as mkdir14, readFile as readFile23, stat as stat5, writeFile as writeFile12 } from "fs/promises";
@@ -20040,7 +21164,7 @@ async function doPullInstall(fullSlug, tool, installRoot, opts = {}) {
   };
 }
 function registryPullCommand() {
-  return new Command29("pull").description("install a package from the public layer into this project").argument(
+  return new Command30("pull").description("install a package from the public layer into this project").argument(
     "<full_slug>",
     "package identifier {username}/{slug}, optionally @{version} or @{range}"
   ).option("--tool <name>", "target tool format (default: work it out from this directory)").option("--target <path>", "install into this directory instead of the current one").option("--with-recommends", "also install recommended (depth-0) dependencies", false).option(
@@ -20269,10 +21393,10 @@ async function applyEmittedFile(abs, f, fullSlug, notes) {
 // src/commands/registry/update.ts
 init_errors();
 init_ui();
-import { Command as Command30 } from "commander";
+import { Command as Command31 } from "commander";
 import semver2 from "semver";
 function registryUpdateCommand() {
-  return new Command30("update").description("update installed packages to their latest in-range versions").argument("[full_slug]", "package identifier {username}/{slug} (omit to update all)").option("--dry-run", "show what would be updated without doing it", false).addHelpText(
+  return new Command31("update").description("update installed packages to their latest in-range versions").argument("[full_slug]", "package identifier {username}/{slug} (omit to update all)").option("--dry-run", "show what would be updated without doing it", false).addHelpText(
     "after",
     "\nEnvironment:\n  KORDIS_API_URL=<url>   ask this registry instead of the linked one\n"
   ).action(async (fullSlugArg, opts) => {
@@ -20406,10 +21530,10 @@ function registryUpdateCommand() {
 
 // src/commands/registry/outdated.ts
 init_ui();
-import { Command as Command31 } from "commander";
+import { Command as Command32 } from "commander";
 import semver3 from "semver";
 function outdatedCommand() {
-  return new Command31("outdated").description("check installed packages for available updates").addHelpText(
+  return new Command32("outdated").description("check installed packages for available updates").addHelpText(
     "after",
     "\nEnvironment:\n  KORDIS_API_URL=<url>   ask this registry instead of the linked one\n"
   ).action(async () => {
@@ -20501,9 +21625,9 @@ function outdatedCommand() {
 // src/commands/registry/versions.ts
 init_errors();
 init_ui();
-import { Command as Command32 } from "commander";
+import { Command as Command33 } from "commander";
 function versionsCommand() {
-  return new Command32("versions").description("list every published version of a package").argument("<full_slug>", "package identifier {username}/{slug}").addHelpText(
+  return new Command33("versions").description("list every published version of a package").argument("<full_slug>", "package identifier {username}/{slug}").addHelpText(
     "after",
     "\nEnvironment:\n  KORDIS_API_URL=<url>   ask this registry instead of the linked one\n"
   ).action(async (fullSlug) => {
@@ -20567,9 +21691,9 @@ function relativeTime(isoString) {
 // src/commands/registry/diff.ts
 init_errors();
 init_ui();
-import { Command as Command33 } from "commander";
+import { Command as Command34 } from "commander";
 function diffCommand() {
-  return new Command33("diff").description("show what changed between two versions of a package").argument(
+  return new Command34("diff").description("show what changed between two versions of a package").argument(
     "<full_slug>",
     "package identifier {username}/{slug}, or {username}/{slug}@{from}..{to}"
   ).argument("[from]", "older version (omit to use the second-latest)").argument("[to]", "newer version (omit to use the latest)").addHelpText(
@@ -20646,7 +21770,7 @@ function diffCommand() {
 }
 
 // src/commands/registry/list.ts
-import { Command as Command34 } from "commander";
+import { Command as Command35 } from "commander";
 init_errors();
 init_ui();
 var SORT_KEYWORDS = ["latest", "popular", "recent", "updated", "stars", "downloads"];
@@ -20669,7 +21793,7 @@ function parseUsername(raw) {
   return parsed.data;
 }
 function listCommand() {
-  return new Command34("list").description("list packages \u2014 your own with no argument, or a public user\u2019s").argument("[username]", "whose packages to list (omit for your own)").option("--limit <n>", "maximum results per page", (v) => parseInt(v, 10), 20).option("--page <n>", "page number for your own packages (1-based)", (v) => parseInt(v, 10), 1).option("--cursor <token>", "continue a public listing from a previous result").option(
+  return new Command35("list").description("list packages \u2014 your own with no argument, or a public user\u2019s").argument("[username]", "whose packages to list (omit for your own)").option("--limit <n>", "maximum results per page", (v) => parseInt(v, 10), 20).option("--page <n>", "page number for your own packages (1-based)", (v) => parseInt(v, 10), 1).option("--cursor <token>", "continue a public listing from a previous result").option(
     "--sort <mode>",
     "latest|popular for your own; stars|downloads|recent|updated for a public listing",
     "latest"
@@ -20767,7 +21891,7 @@ init_push();
 // src/commands/recall.ts
 init_src();
 init_config();
-import { Command as Command36 } from "commander";
+import { Command as Command37 } from "commander";
 import { basename as basename2, resolve as resolve13 } from "path";
 init_index_build();
 init_cloud_brain();
@@ -20775,7 +21899,7 @@ init_errors();
 init_vault();
 init_ui();
 function recallCommand() {
-  return new Command36("recall").description("recall memory cards for a question").argument("<query>", "what you want to remember").option("--vault <path>", "which brain to search").option("--local", "search the brain on this machine, even when signed in to a hosted one").option(
+  return new Command37("recall").description("recall memory cards for a question").argument("<query>", "what you want to remember").option("--vault <path>", "which brain to search").option("--local", "search the brain on this machine, even when signed in to a hosted one").option(
     "--brain <name>",
     "search one existing hosted brain by name or id, without changing the pointer"
   ).option("--scope <scope>", "restrict to one scope").option("--limit <n>", "max cards", (v) => parseInt(v, 10), 8).option(
@@ -20797,6 +21921,8 @@ function recallCommand() {
       let unsearchedLocal = [];
       let searchedLocalName = null;
       let isScaffolding;
+      let templatesWithheld = 0;
+      let spread = null;
       let reasons;
       let pathOf;
       let entries;
@@ -20825,13 +21951,25 @@ function recallCommand() {
           // older clients: the route applies a ceiling only when one arrives,
           // so a CLI that predates this field gets the whole ranking rather
           // than a trimmed packet it cannot describe.
-          budget
+          budget,
+          // Two, like a folder brain. The server holds the content the check
+          // needs; a server older than the field ignores it and caps nothing.
+          templateSlots: TEMPLATE_SLOTS
         });
-        rows = answered.memory_cards.map((card) => ({ card, handle: card.handle, stage: {} }));
+        const unfilledIds = new Set(
+          answered.memory_cards.filter((card) => card.unfilled === true).map((card) => card.id)
+        );
+        rows = answered.memory_cards.map(({ unfilled: _unfilled, ...card }) => ({
+          card,
+          handle: card.handle,
+          stage: {}
+        }));
+        spread = isScopeSpread(answered.scope_spread) ? answered.scope_spread : null;
+        templatesWithheld = Number.isInteger(answered.templates_withheld) && (answered.templates_withheld ?? 0) > 0 ? answered.templates_withheld : 0;
         if (rows.length === 0) {
           unsearchedBrains = await listCloudBrains(cloud.token, cloud.apiUrl, { retries: 0 }).then((all) => all.filter((b) => b.id !== cloud.brainId)).catch(() => []);
         }
-        isScaffolding = () => false;
+        isScaffolding = (card) => unfilledIds.has(card.id);
         reasons = /* @__PURE__ */ new Map();
         pathOf = () => null;
         entries = null;
@@ -20861,8 +21999,28 @@ function recallCommand() {
           ...depth === void 0 ? {} : { depth },
           tokenBudget: budget
         });
-        result = local;
+        const byId = new Map(built.entries.map((e) => [e.memory.id, e]));
+        const scaffolding = await scaffoldingAmong(
+          adapter,
+          local.memory_cards.map((card) => {
+            const entry = byId.get(card.id);
+            return { path: entry?.path ?? "", title: entry?.memory.title ?? "" };
+          })
+        );
+        isScaffolding = (card) => scaffolding.has(byId.get(card.id)?.path ?? "");
+        const capped2 = capTemplates(local.memory_cards, isScaffolding);
+        templatesWithheld = capped2.withheld.length;
+        result = { ...local, memory_cards: capped2.kept };
         entries = built.entries;
+        if (!opts.scope) {
+          spread = scopeSpread(
+            result.memory_cards.map((card) => {
+              const memory = byId.get(card.id)?.memory;
+              return memory === void 0 ? null : declaredScope(memory);
+            }),
+            built.entries.map((e) => declaredScope(e.memory))
+          );
+        }
         if (result.memory_cards.length === 0) {
           searchedLocalName = basename2(resolve13(brain.root));
           unsearchedLocal = await loadConfig().then(
@@ -20882,7 +22040,6 @@ function recallCommand() {
           returnedIds: result.memory_cards.map((card) => card.id)
         });
         const allIds = built.entries.map((e) => e.memory.id);
-        const byId = new Map(built.entries.map((e) => [e.memory.id, e]));
         pathOf = (card) => byId.get(card.id)?.path ?? null;
         rows = await Promise.all(
           result.memory_cards.map(async (card) => ({
@@ -20891,14 +22048,6 @@ function recallCommand() {
             stage: await stageFor(adapter, byId.get(card.id), detail)
           }))
         );
-        const scaffolding = await scaffoldingAmong(
-          adapter,
-          rows.map(({ card }) => {
-            const entry = byId.get(card.id);
-            return { path: entry?.path ?? "", title: entry?.memory.title ?? "" };
-          })
-        );
-        isScaffolding = (card) => scaffolding.has(byId.get(card.id)?.path ?? "");
         reasons = result.conflicts.length > 0 ? await conflictReasons(brain.root, result.conflicts, byId) : /* @__PURE__ */ new Map();
       }
       printDual({
@@ -20935,7 +22084,11 @@ function recallCommand() {
             // Same order as `between`, so a parser can zip the three arrays.
             reason: conflict.between.map((id) => reasons.get(id) ?? null)
           })),
-          ...result.truncated === void 0 ? {} : { truncated: result.truncated }
+          ...result.truncated === void 0 ? {} : { truncated: result.truncated },
+          // Counted, never silent: these matched and were left off because
+          // they are still exactly what `init` wrote.
+          ...templatesWithheld > 0 ? { templates_withheld: templatesWithheld } : {},
+          ...spread === null ? {} : { scope_spread: spread }
         },
         human: () => {
           const brainHeading = answeredBy === null ? "" : ` \u2014 ${oneLine(answeredBy, WIDTH.title)}`;
@@ -21027,20 +22180,48 @@ ${unsearchedLocal.map(
               )
             );
           }
-          if (otherScript) sayWhy();
-          const glossOn = rows.findIndex(
-            ({ card }) => card.confidence === "stated" && !isScaffolding(card)
-          );
-          for (const [i, { card, handle, stage }] of rows.entries()) {
-            const mark = reachedSomethingWritten && isScaffolding(card);
+          const templateCount = rows.filter(({ card }) => isScaffolding(card)).length;
+          if (reachedSomethingWritten && templateCount > 0) {
             printHuman(
-              renderCard(
-                i + 1,
-                card,
-                handle,
-                detail,
-                stage,
-                i === glossOn,
+              c.gray(
+                `  ${templateCount} of ${rows.length} cards ${templateCount === 1 ? "is" : "are"} still the untouched starter template \u2014 marked "not filled in yet" below.
+`
+              )
+            );
+          }
+          if (spread !== null) {
+            const others = spread.elsewhere.map((s) => `\`${oneLine(s, WIDTH.title)}\``).join(", ");
+            const more = spread.elsewhere_total - spread.elsewhere.length;
+            printHuman(
+              c.gray(
+                (spread.cards === spread.of ? `  ${spread.cards === 1 ? "The one card is" : `All ${spread.cards} cards are`} from \`${oneLine(spread.scope, WIDTH.title)}\`.` : `  Every card with a project is from \`${oneLine(spread.scope, WIDTH.title)}\` (${spread.cards} of ${spread.of}).`) + `
+  Also in this brain: ${others}${more > 0 ? ` and ${more} more` : ""} \u2014 add \`--scope <name>\` to ask one of them.
+`
+              )
+            );
+          }
+          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.
+`
+              )
+            );
+          }
+          if (otherScript) sayWhy();
+          const glossOn = rows.findIndex(
+            ({ card }) => card.confidence === "stated" && !isScaffolding(card)
+          );
+          for (const [i, { card, handle, stage }] of rows.entries()) {
+            const mark = reachedSomethingWritten && isScaffolding(card);
+            printHuman(
+              renderCard(
+                i + 1,
+                card,
+                handle,
+                detail,
+                stage,
+                i === glossOn,
                 mark,
                 // Only when `--brain` aimed this elsewhere. A recall of the
                 // brain this machine already points at mints handles `open`
@@ -21167,6 +22348,7 @@ function renderCard(n, card, handle, detail, stage, glossHere = false, scaffoldi
     ].filter(Boolean);
     out.push(oneLine(marks.join(c.gray(" \xB7 ")), WIDTH.text));
   }
+  if (card.matched === "meaning") out.push(c.gray(MEANING_ONLY_NOTE));
   if (glossHere && !scaffolding) {
     out.push(c.gray("stated = these fields came from the note, not from inference"));
   }
@@ -21249,17 +22431,21 @@ function dominantScriptOf(text) {
 function scriptsIn(text) {
   return new Set(scriptCounts(text).keys());
 }
+function isScopeSpread(value) {
+  const v = value;
+  return typeof v === "object" && v !== null && typeof v.scope === "string" && Number.isInteger(v.cards) && Number.isInteger(v.of) && Number.isInteger(v.elsewhere_total) && Array.isArray(v.elsewhere) && v.elsewhere.every((s) => typeof s === "string");
+}
 
 // src/commands/resurface.ts
 init_deadline();
 init_src();
-import { Command as Command37 } from "commander";
+import { Command as Command38 } from "commander";
 init_index_build();
 init_cloud_brain();
 init_vault();
 init_ui();
 function resurfaceCommand() {
-  return new Command37("resurface").description("what is worth having in view right now, without being asked").option("--context-dir <path>", "where the work is happening (default: cwd)").option("--limit <n>", "how many cards", (v) => parseInt(v, 10), 5).option("--vault <path>", "which brain").option("--local", "use the brain on this machine, even when signed in to a hosted one").option(
+  return new Command38("resurface").description("what is worth having in view right now, without being asked").option("--context-dir <path>", "where the work is happening (default: cwd)").option("--limit <n>", "how many cards", (v) => parseInt(v, 10), 5).option("--vault <path>", "which brain").option("--local", "use the brain on this machine, even when signed in to a hosted one").option(
     "--brain <name>",
     "read one existing hosted brain by name or id, without changing the pointer"
   ).option(
@@ -21301,7 +22487,6 @@ function resurfaceCommand() {
           // so it is the only side that can answer this.
           here: (event) => isInside(event.context_dir, contextDir)
         });
-        const TEMPLATE_SLOTS = 2;
         const untouchedPaths = await untouchedBase(
           adapter,
           ranked.map((r) => r.entry.path)
@@ -21373,9 +22558,7 @@ function resurfaceCommand() {
                 )
               );
             }
-            const noEvidenceYet = !rankedShown.some(
-              ({ why }) => why.some((w) => w.startsWith("recalled"))
-            );
+            const noEvidenceYet = !rankedShown.some(({ used }) => used);
             for (const [i, { entry, why }] of rankedShown.entries()) {
               const blank = untouched.has(entry.path);
               printHuman(`### ${i + 1}. ${oneLine(entry.memory.title, WIDTH.title)}`);
@@ -21484,11 +22667,11 @@ rank by project yet, so that is not one of the signals above.`
 }
 
 // src/commands/rules.ts
-import { Command as Command38 } from "commander";
+import { Command as Command39 } from "commander";
 init_cloud_brain();
 init_ui();
 function rulesCommand() {
-  return new Command38("rules").description("the user\u2019s standing decisions \u2014 what binds you here").option("--vault <path>", "which brain").option("--local", "use the brain on this machine, even when signed in to a hosted one").option(
+  return new Command39("rules").description("the user\u2019s standing decisions \u2014 what binds you here").option("--vault <path>", "which brain").option("--local", "use the brain on this machine, even when signed in to a hosted one").option(
     "--brain <name>",
     "read one existing hosted brain by name or id, without changing the pointer"
   ).action(async (opts) => {
@@ -21648,89 +22831,160 @@ If the rest are decisions that no longer decide anything: \`memgineering retire
 init_setup();
 
 // src/commands/update.ts
-import { Command as Command40 } from "commander";
+init_brand();
+init_version();
 init_config();
+import { spawn as spawn3 } 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 { join as join28 } from "path";
+import { Command as Command41 } from "commander";
 
-// src/lib/provenance.ts
-import { execFile } from "child_process";
-import { realpath as realpath3 } from "fs/promises";
-import { dirname as dirname9, join as join25, resolve as resolve14 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import { promisify } from "util";
-var run = promisify(execFile);
-var MANAGERS = [
-  {
-    kind: "npm",
-    bin: "npm",
-    prefixArgs: ["prefix", "-g"],
-    install: "npm i -g memgineering@latest"
-  },
-  {
-    kind: "pnpm",
-    bin: "pnpm",
-    prefixArgs: ["root", "-g"],
-    install: "pnpm add -g memgineering@latest"
-  },
-  { kind: "bun", bin: "bun", prefixArgs: ["pm", "bin", "-g"], install: "bun add -g memgineering" }
-];
-async function detectProvenance(selfPath) {
-  const entry = selfPath ?? fileURLToPath3(import.meta.url);
-  const selfDir = await realpath3(dirname9(entry)).catch(() => dirname9(entry));
-  if (/[\\/]_npx[\\/]|[\\/]\.npm[\\/]_cacache[\\/]/.test(selfDir)) {
-    return {
-      kind: "npx",
-      selfDir,
-      prefix: null,
-      command: "npm i -g memgineering@latest",
-      reason: "this is a one-off npx run, not an installed copy"
-    };
+// 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.";
+async function claimFullSetupNotice() {
+  const marker = join26(brandHome(), "setup-notice-shown");
+  try {
+    await readFile25(marker, "utf8");
+    return false;
+  } catch {
   }
-  for (const manager of MANAGERS) {
-    const prefix = await prefixOf(manager.bin, manager.prefixArgs);
-    if (prefix === null) continue;
-    if (isInside2(selfDir, prefix)) {
-      return {
-        kind: manager.kind,
-        selfDir,
-        prefix,
-        command: manager.install,
-        reason: null
-      };
-    }
+  try {
+    await mkdir16(brandHome(), { recursive: true });
+    await writeFile13(marker, `${(/* @__PURE__ */ new Date()).toISOString()}
+`);
+  } catch {
   }
-  const local = selfDir.includes(`${"node_modules"}`);
-  return {
-    kind: local ? "local" : "unknown",
-    selfDir,
-    prefix: null,
-    command: "npm i -g memgineering@latest",
-    reason: local ? "this copy is a project dependency, not a global install" : "no package manager on PATH owns the directory this copy is in \u2014 under nvm, asdf, Volta or mise that usually means a different Node version is active than the one it was installed with"
-  };
+  return true;
 }
-function canSelfUpdate(p) {
-  return p.kind === "npm" || p.kind === "pnpm" || p.kind === "bun";
+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.
+`;
+function nextStepFor(cfg, signedIn = false) {
+  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 prefixOf(bin, args) {
+async function currentNextStep() {
   try {
-    const { stdout } = await run(bin, args, { timeout: 5e3 });
-    const value = stdout.trim();
-    return value === "" ? null : await realpath3(value).catch(() => value);
+    const stored = await readCredentials().catch(() => null);
+    return nextStepFor(await loadConfig(), stored !== null && stored.api_url === apiUrl());
   } catch {
     return null;
   }
 }
-function isInside2(child, parent) {
-  const c2 = resolve14(child);
-  const p = resolve14(parent);
-  return c2 === p || c2.startsWith(p.endsWith("/") ? p : `${p}/`);
-}
+
+// src/commands/update.ts
+init_provenance();
 
 // src/lib/update-check.ts
 init_atomic();
 init_brand();
 import { execFile as execFile2 } from "child_process";
-import { mkdir as mkdir16, readFile as readFile25, writeFile as writeFile13 } from "fs/promises";
-import { join as join26 } from "path";
+import { mkdir as mkdir17, readFile as readFile26, writeFile as writeFile14 } from "fs/promises";
+import { join as join27 } from "path";
 import { promisify as promisify2 } from "util";
 import semver4 from "semver";
 import { z as z33 } from "zod";
@@ -21811,11 +23065,11 @@ var UpdateStateSchema = z33.object({
   message: z33.string().nullable()
 });
 function statePath() {
-  return join26(brandHome(), "update-state.json");
+  return join27(brandHome(), "update-state.json");
 }
 async function readUpdateState() {
   try {
-    const parsed = UpdateStateSchema.safeParse(JSON.parse(await readFile25(statePath(), "utf8")));
+    const parsed = UpdateStateSchema.safeParse(JSON.parse(await readFile26(statePath(), "utf8")));
     return parsed.success ? parsed.data : null;
   } catch {
     return null;
@@ -21823,7 +23077,7 @@ async function readUpdateState() {
 }
 async function writeUpdateState(state) {
   try {
-    await mkdir16(brandHome(), { recursive: true });
+    await mkdir17(brandHome(), { recursive: true });
     await writeThenRename(statePath(), `${JSON.stringify(state, null, 2)}
 `);
   } catch {
@@ -21879,70 +23133,106 @@ function shortMessage(err) {
 // src/commands/update.ts
 init_ui();
 function updateCommand() {
-  return new Command40("update").description("update memgineering itself").option("--check", "report what is available and change nothing").action(async (opts) => {
-    const status = await checkForUpdate(VERSION);
-    const provenance = await detectProvenance();
-    const previous = await readUpdateState();
-    const cfg = await loadConfig();
-    await saveConfig({
-      ...cfg,
-      system: { ...cfg.system, lastUpdateCheck: (/* @__PURE__ */ new Date()).toISOString() }
-    });
-    if (!status.updateAvailable) {
-      printDual({
-        json: { ...status, provenance: provenance.kind, updated: false, previous },
-        human: () => {
-          printHuman(
-            status.latest === null ? `memgineering ${VERSION} \u2014 could not reach npm to check for a newer version.` : `memgineering ${VERSION} is current.`
-          );
-          reportNotice(status.notice);
-          reportBelowMinimum(status.belowMinimum);
-        }
-      });
-      return;
+  return new Command41("update").description("update memgineering itself").option("--check", "report what is available and change nothing").action(async (opts) => {
+    const inherited = process.env[UPDATE_CLAIM_ENV] || void 0;
+    try {
+      await runUpdate(opts, inherited);
+    } finally {
+      if (inherited !== void 0) await releaseUpdateSlot(inherited);
     }
-    if (opts.check || !canSelfUpdate(provenance)) {
-      printDual({
-        json: {
-          ...status,
-          provenance: provenance.kind,
-          reason: provenance.reason,
-          command: provenance.command,
-          updated: false
-        },
-        human: () => {
-          printHuman(`memgineering ${status.latest} is available (you have ${VERSION}).
+  });
+}
+async function runUpdate(opts, inherited) {
+  const status = await checkForUpdate(VERSION);
+  const provenance = await detectProvenance();
+  const previous = await readUpdateState();
+  const cfg = await loadConfig();
+  await saveConfig({
+    ...cfg,
+    system: { ...cfg.system, lastUpdateCheck: (/* @__PURE__ */ new Date()).toISOString() }
+  });
+  if (!status.updateAvailable) {
+    printDual({
+      json: { ...status, provenance: provenance.kind, updated: false, previous },
+      human: () => {
+        printHuman(
+          status.latest === null ? `memgineering ${VERSION} \u2014 could not reach npm to check for a newer version.` : `memgineering ${VERSION} is current.`
+        );
+        reportNotice(status.notice);
+        reportBelowMinimum(status.belowMinimum);
+      }
+    });
+    return;
+  }
+  if (opts.check || !canSelfUpdate(provenance)) {
+    printDual({
+      json: {
+        ...status,
+        provenance: provenance.kind,
+        reason: provenance.reason,
+        command: provenance.command,
+        updated: false
+      },
+      human: () => {
+        printHuman(`memgineering ${status.latest} is available (you have ${VERSION}).
 `);
-          if (!opts.check && provenance.reason) {
-            printHuman(c.yellow(`Not updating automatically \u2014 ${provenance.reason}.
+        if (!opts.check && provenance.reason) {
+          printHuman(c.yellow(`Not updating automatically \u2014 ${provenance.reason}.
 `));
-          }
-          printHuman(`Run:  ${provenance.command}`);
-          reportNotice(status.notice);
-          reportBelowMinimum(status.belowMinimum);
         }
-      });
-      return;
-    }
-    printHuman(c.gray(`Updating ${VERSION} \u2192 ${status.latest}\u2026`));
-    const result = await performUpdate({ command: provenance.command, from: VERSION });
-    await writeUpdateState(result);
+        printHuman(`Run:  ${provenance.command}`);
+        reportNotice(status.notice);
+        reportBelowMinimum(status.belowMinimum);
+      }
+    });
+    return;
+  }
+  const held = await holdUpdateSlot(inherited);
+  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.";
     printDual({
-      json: { ...status, provenance: provenance.kind, updated: result.ok, result },
+      json: {
+        ...status,
+        provenance: provenance.kind,
+        updated: false,
+        reason: "update_in_progress",
+        ...started ? { started_at: started } : {},
+        hint
+      },
       human: () => {
-        if (result.ok) {
-          printHuman(c.green(`Updated to ${result.to}.`));
-          printHuman(c.gray("Restart your agent session to pick up any changed guidance."));
-          return;
-        }
-        printHuman(c.yellow(`Update did not complete: ${result.message}`));
-        printHuman(c.gray(`Run it yourself:  ${provenance.command}`));
+        printHuman(
+          `memgineering ${status.latest} is available, and an update is already installing${started ? ` (started ${started})` : ""} \u2014 not starting a second one.`
+        );
+        printHuman(c.gray(hint));
       }
     });
+    return;
+  }
+  printHuman(c.gray(`Updating ${VERSION} \u2192 ${status.latest}\u2026`));
+  let result;
+  try {
+    result = await performUpdate({ command: provenance.command, from: VERSION });
+    await writeUpdateState(result);
+  } finally {
+    await releaseUpdateSlot(held);
+  }
+  printDual({
+    json: { ...status, provenance: provenance.kind, updated: result.ok, result },
+    human: () => {
+      if (result.ok) {
+        printHuman(c.green(`Updated to ${result.to}.`));
+        printHuman(c.gray("Restart your agent session to pick up any changed guidance."));
+        return;
+      }
+      printHuman(c.yellow(`Update did not complete: ${result.message}`));
+      printHuman(c.gray(`Run it yourself:  ${provenance.command}`));
+    }
   });
 }
-async function backgroundUpdateNotice() {
+async function backgroundUpdateNotice(deps = {}) {
   try {
+    if (deps.verb !== void 0 && HOOK_VERBS.has(deps.verb)) return;
     const cfg = await loadConfig();
     const now = /* @__PURE__ */ new Date();
     if (!shouldCheck(cfg.system.lastUpdateCheck, now)) {
@@ -21950,8 +23240,22 @@ async function backgroundUpdateNotice() {
       return;
     }
     await saveConfig({ ...cfg, system: { ...cfg.system, lastUpdateCheck: now.toISOString() } });
-    const status = await checkForUpdate(VERSION);
+    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 token = newClaimToken();
+      if (canSelfUpdate(provenance) && await claimUpdateSlot(token)) {
+        (deps.startUpdate ?? ((t) => startDetachedUpdate(spawn3, 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.`
+          )
+        );
+        if (status.notice) notice(c.gray(`note from memgineering.com: "${status.notice}"`));
+        return;
+      }
+    }
     if (status.belowMinimum) {
       notice(
         c.yellow(
@@ -21965,10 +23269,73 @@ async function backgroundUpdateNotice() {
   } catch {
   }
 }
+function startDetachedUpdate(spawnImpl = spawn3, token) {
+  const child = spawnImpl(process.execPath, [process.argv[1] ?? "", "update"], {
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      MEMGINEERING_NO_UPDATE: "1",
+      // The claim this run took, so the child installs under it and gives it
+      // back, instead of finding it held and standing down.
+      ...token === void 0 ? {} : { [UPDATE_CLAIM_ENV]: token }
+    }
+  });
+  child.on("error", () => {
+    if (token !== void 0) void releaseUpdateSlot(token);
+  });
+  child.unref();
+}
+var UPDATE_CLAIM_ENV = "MEMGINEERING_UPDATE_CLAIM";
+function newClaimToken() {
+  return `${(/* @__PURE__ */ new Date()).toISOString()} pid=${process.pid} ${randomBytes2(6).toString("hex")}`;
+}
+async function claimOwner() {
+  try {
+    return (await readFile27(join28(brandHome(), "update-running"), "utf8")).trim() || null;
+  } catch {
+    return null;
+  }
+}
+async function releaseUpdateSlot(token) {
+  if (await claimOwner() !== token) return;
+  await unlink4(join28(brandHome(), "update-running")).catch(() => void 0);
+}
+async function holdUpdateSlot(inherited) {
+  if (inherited !== void 0 && await claimOwner() === inherited) return inherited;
+  const token = newClaimToken();
+  if (await claimUpdateSlot(token)) return token;
+  if (await claimOwner() === null && await claimUpdateSlot(token)) return token;
+  return null;
+}
+var HOOK_VERBS = /* @__PURE__ */ new Set(["guard", "resurface"]);
+var UPDATE_CLAIM_MS = 15 * 6e4;
+async function claimUpdateSlot(token = newClaimToken()) {
+  const path = join28(brandHome(), "update-running");
+  try {
+    await mkdir18(brandHome(), { recursive: true });
+    const handle = await open(path, "wx");
+    await handle.writeFile(`${token}
+`);
+    await handle.close();
+    return true;
+  } catch (err) {
+    if (err?.code !== "EEXIST") return false;
+  }
+  try {
+    if (Date.now() - (await stat7(path)).mtimeMs >= UPDATE_CLAIM_MS) await unlink4(path);
+  } catch {
+  }
+  return false;
+}
 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}`));
+  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."
+    )
+  );
 }
 function reportNotice(text) {
   if (!text) return;
@@ -21986,16 +23353,16 @@ function reportBelowMinimum(below) {
 
 // src/commands/undo.ts
 init_src();
-import { readFile as readFile26, rm as rm8 } from "fs/promises";
-import { join as join27 } from "path";
-import { Command as Command41 } from "commander";
+import { readFile as readFile28, rm as rm8 } from "fs/promises";
+import { join as join29 } from "path";
+import { Command as Command42 } from "commander";
 init_atomic();
 init_errors();
 init_cloud_brain();
 init_vault();
 init_ui();
 function undoCommand() {
-  return new Command41("undo").description("take back the last change, or a named one").argument("[op]", "operation id (default: the most recent)").option("--reason <text>", "why it is being taken back \u2014 kept in the ledger").option("--vault <path>", "which brain to act on").option("--local", "act on the brain on this machine, even when signed in to a hosted one").action(
+  return new Command42("undo").description("take back the last change, or a named one").argument("[op]", "operation id (default: the most recent)").option("--reason <text>", "why it is being taken back \u2014 kept in the ledger").option("--vault <path>", "which brain to act on").option("--local", "act on the brain on this machine, even when signed in to a hosted one").action(
     async (opId, opts) => {
       const rationale = sanitizeRationale(opts.reason);
       const where = await resolveTarget({
@@ -22084,8 +23451,8 @@ ${matches.slice(0, 8).map((id) => `  ${id}`).join("\n")}${matches.length > 8 ? "
         );
       }
       const record = await withWriteLock(brain.root, async () => {
-        const absolute = join27(brain.root, target.target);
-        const current = await readFile26(absolute, "utf8").catch(() => null);
+        const absolute = join29(brain.root, target.target);
+        const current = await readFile28(absolute, "utf8").catch(() => null);
         const actualHash = current === null ? null : hashContent(current);
         if (actualHash !== target.hash_after) {
           throw memgError(
@@ -22147,7 +23514,7 @@ function minutesSince(iso) {
   return Math.max(0, Math.floor((Date.now() - at) / 6e4));
 }
 async function reverse(brain, op, current) {
-  const absolute = join27(brain.root, op.target);
+  const absolute = join29(brain.root, op.target);
   if (op.verb === "remember") {
     if (current === null) {
       throw memgError(
@@ -22200,11 +23567,11 @@ async function reverse(brain, op, current) {
   return reverted;
 }
 async function conflictHint(vaultRoot, op) {
-  const base = `Nothing was changed. Someone \u2014 you, an editor, or a sync \u2014 has written to that file since.
+  const base2 = `Nothing was changed. Someone \u2014 you, an editor, or a sync \u2014 has written to that file since.
 Read what it says now, then decide what should stay.`;
   const snapshot = await readSnapshot(vaultRoot, op.op_id);
-  return snapshot === null ? base : `${base}
-The text from before that change is still on this machine: ${join27(snapshotDir(vaultRoot), `${op.op_id}.txt`)}`;
+  return snapshot === null ? base2 : `${base2}
+The text from before that change is still on this machine: ${join29(snapshotDir(vaultRoot), `${op.op_id}.txt`)}`;
 }
 
 // src/commands/brains.ts
@@ -22213,19 +23580,19 @@ init_api_client();
 init_cloud_brain();
 init_config();
 init_ui();
-import { Command as Command42 } from "commander";
+import { Command as Command43 } from "commander";
 import stringWidth from "string-width";
 var NAME_WIDTH2 = 48;
 function brainsCommand() {
-  return new Command42("brains").description("list the hosted brains on your account, and which one this machine reads").addHelpText(
+  return new Command43("brains").description("list the hosted brains on your account, and which one this machine reads").addHelpText(
     "after",
     "\nReads only. `memgineering use --brain <name>` points this machine at one of\nthem. `memgineering create <name>` makes a new empty one, and\n`push --brain <name>` makes one from a folder on this machine."
   ).action(async () => {
-    const base = apiUrl();
-    const credentials = await requireCredentials(base);
-    const brains = await listCloudBrains(credentials.token, base);
+    const base2 = apiUrl();
+    const credentials = await requireCredentials(base2);
+    const brains = await listCloudBrains(credentials.token, base2);
     const pointer = (await loadConfig()).brain.cloud;
-    const currentId = pointer?.api_url === base ? pointer.id : null;
+    const currentId = pointer?.api_url === base2 ? pointer.id : null;
     if (brains.length === 0) {
       throw memgError(
         "invalid_input",
@@ -22253,7 +23620,7 @@ function brainsCommand() {
         // that answered none of the rest. Two round-test agents ran all three.
         // The name is free here; it came back with the token.
         account: { id: credentials.account_id, name: credentials.display_name },
-        server: base,
+        server: base2,
         brains: rows,
         count: rows.length,
         // Named at the top level too, so a caller does not have to scan the
@@ -22297,7 +23664,7 @@ init_credentials();
 init_cloud_brain();
 init_config();
 import { isAbsolute as isAbsolute5, relative as relative2, resolve as resolve15 } from "path";
-import { Command as Command43 } from "commander";
+import { Command as Command44 } from "commander";
 init_vault();
 init_ui();
 function lostDefaultLines(missing) {
@@ -22316,7 +23683,7 @@ var VIA_MEANS = {
   default: "because it is your default brain (`memgineering use --default <path>` changes it)"
 };
 function useCommand() {
-  return new Command43("use").description(
+  return new Command44("use").description(
     "say which brain answers here \u2014 `--brain <name>` for the whole machine, or a path to bind this folder"
   ).argument("[brain]", "path to the brain \u2014 omit to show what this folder resolves to").option("--brain <name>", "point this machine at a hosted brain, by its name or id").option("--here <dir>", "write the pointer in this directory instead of the cwd").option(
     "--default",
@@ -22542,8 +23909,8 @@ async function pointAtHosted(named, opts, path) {
       "They point different things. `--brain <name>` moves the one hosted brain this machine reads, which is a single setting for the whole machine; a path, `--default` and `--here` all bind a FOLDER on this disk. Run them separately."
     );
   }
-  const base = apiUrl();
-  const credentials = await requireCredentials(base).catch((err) => {
+  const base2 = apiUrl();
+  const credentials = await requireCredentials(base2).catch((err) => {
     if (err instanceof MemgError && err.code === "not_signed_in") {
       throw memgError(
         "not_signed_in",
@@ -22553,7 +23920,7 @@ async function pointAtHosted(named, opts, path) {
     }
     throw err;
   });
-  const brains = await listCloudBrains(credentials.token, base);
+  const brains = await listCloudBrains(credentials.token, base2);
   if (brains.length === 0) {
     throw memgError(
       "invalid_input",
@@ -22571,11 +23938,11 @@ async function pointAtHosted(named, opts, path) {
   }
   const config = await loadConfig();
   const previous = config.brain.cloud ?? null;
-  const unchanged = previous?.id === found.id && previous.api_url === base && previous.name === found.name;
+  const unchanged = previous?.id === found.id && previous.api_url === base2 && previous.name === found.name;
   if (!unchanged) {
     await saveConfig({
       ...config,
-      brain: { ...config.brain, cloud: { id: found.id, name: found.name, api_url: base } }
+      brain: { ...config.brain, cloud: { id: found.id, name: found.name, api_url: base2 } }
     });
   }
   printDual({
@@ -22583,7 +23950,7 @@ async function pointAtHosted(named, opts, path) {
       brain: {
         id: found.id,
         name: found.name,
-        api_url: base,
+        api_url: base2,
         // Carried because the human line says it. A caller that has to ask a
         // second time to learn the destination is empty is a caller that will
         // not ask.
@@ -22624,16 +23991,16 @@ async function pointAtHosted(named, opts, path) {
 // src/commands/whoami.ts
 init_api_client();
 init_ui();
-import { Command as Command44 } from "commander";
+import { Command as Command45 } from "commander";
 function whoamiCommand() {
-  return new Command44("whoami").description("show which account this machine is signed in as").action(async () => {
-    const base = apiUrl();
-    const credentials = await requireCredentials(base);
+  return new Command45("whoami").description("show which account this machine is signed in as").action(async () => {
+    const base2 = apiUrl();
+    const credentials = await requireCredentials(base2);
     const res = await apiRequest({
       method: "GET",
       path: "/v1/me",
       token: credentials.token,
-      baseUrl: base
+      baseUrl: base2
     });
     const account = res.body?.account ?? {};
     const live = res.body?.tokens?.live ?? null;
@@ -22647,7 +24014,7 @@ function whoamiCommand() {
           created_at: account.created_at ?? null
         },
         tokens: { live },
-        api_url: base,
+        api_url: base2,
         signed_in_at: credentials.signed_in_at,
         registry: credentials.registry ? {
           username: credentials.registry.username,
@@ -22662,7 +24029,7 @@ function whoamiCommand() {
           )
         );
         if (account.email) printHuman(c.gray(`  ${oneLine(account.email, WIDTH.title)}`));
-        printHuman(c.gray(`  on ${base}`));
+        printHuman(c.gray(`  on ${base2}`));
         if (credentials.registry) {
           printHuman(
             c.gray(
@@ -22688,94 +24055,6 @@ function whoamiCommand() {
   });
 }
 
-// src/lib/next-step.ts
-init_api_client();
-init_credentials();
-init_config();
-function isSetUp(cfg) {
-  return Object.keys(cfg.system.installed).length > 0;
-}
-var FINISH_SETUP = `## memgineering is installed. It is NOT set up yet.
-
-**TO THE AGENT READING THIS** \u2014 finish it now, in this same turn. Do not print
-this for your user and stop: the command is yours to run.
-
-\`\`\`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 when
-they do, after your turn has ended.
-
-So: run it, then tell them **in their language** that you opened the setup
-screen in their browser and they can finish it there. It prints a short code
-first \u2014 show them that code, because the screen asks whether they started this
-and expects 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 URL to open on the
-computer they are actually sitting at.
-
-\`setup --agent\` is NOT the safe fallback. It answers every one of those
-questions on the user's behalf, and \`--no-login\` answers the biggest one \u2014
-no account, so the memory cannot follow them to another machine, which they
-find out weeks later. Run it only when they have said they would rather you
-decided, or when this machine genuinely 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.
-
-Then read \`memgineering-setup\` for what to do with the brain it points at.`;
-var CONNECT_A_BRAIN = `## memgineering is set up, and no brain is connected.
-
-**TO THE AGENT READING THIS** \u2014 a brain is a folder of markdown notes. Until one
-is connected there is nothing to recall and nowhere to remember. Pick with your
-user, then run it yourself:
-
-\`\`\`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.
-`;
-function nextStepFor(cfg, signedIn = false) {
-  if (signedIn && cfg.brain.cloud === void 0) {
-    return { id: "point_at_a_brain", markdown: POINT_AT_A_BRAIN };
-  }
-  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);
-    return nextStepFor(await loadConfig(), stored !== null && stored.api_url === apiUrl());
-  } catch {
-    return null;
-  }
-}
-
 // src/program.ts
 init_ui();
 init_brand();
@@ -22785,11 +24064,12 @@ var HOMONYM_VERBS = ["pull", "push", "update"];
 var NO_FLAT_ALIAS = new Set(HOMONYM_VERBS);
 
 // src/program.ts
+init_version();
 function buildProgram() {
-  const program = new Command45("memgineering").version(VERSION).description("memgineering \u2014 one memory for the AI you connect").option("--json", "emit JSON to stdout instead of markdown", false).hook("preAction", async (thisCommand, actionCommand) => {
+  const program = new Command46("memgineering").version(VERSION).description("memgineering \u2014 one memory for the AI you connect").option("--json", "emit JSON to stdout instead of markdown", false).hook("preAction", async (thisCommand, actionCommand) => {
     const opts = thisCommand.optsWithGlobals();
     if (opts.json || process.env[BRAND.jsonEnvVar] === "1") setJsonMode(true);
-    await announceNextStep(commandPath(actionCommand));
+    await announceNextStep(commandPath(actionCommand), "verb");
   });
   configureGroupedHelp(program);
   program.addCommand(recallCommand());
@@ -22815,7 +24095,7 @@ function buildProgram() {
     diffCommand,
     listCommand
   ];
-  const registry = new Command45("registry").description(
+  const registry = new Command46("registry").description(
     "the public layer: find, read, adapt, publish, install and keep packages current"
   );
   for (const factory of publicLayer) registry.addCommand(factory());
@@ -22842,6 +24122,8 @@ function buildProgram() {
   program.addCommand(baseWriteCommand());
   program.addCommand(retireCommand());
   program.addCommand(unretireCommand());
+  program.addCommand(rescopeCommand());
+  program.addCommand(expireCommand());
   program.addCommand(retractCommand());
   program.addCommand(excludeCommand());
   program.addCommand(unexcludeCommand());
@@ -22890,15 +24172,16 @@ function commandPath(cmd) {
   const parent = cmd.parent;
   return parent && parent.parent ? `${parent.name()} ${cmd.name()}` : cmd.name();
 }
-async function announceNextStep(commandName, forPerson = false) {
+async function announceNextStep(commandName, reader) {
   if (announced) return;
   if (WITHOUT_NEXT_STEP.has(commandName)) return;
   const step = await currentNextStep();
   if (step === null) return;
   announced = true;
-  if (forPerson && step.id === "finish_setup") {
+  if (step.id === "finish_setup" && reader !== "full") {
+    const text = reader === "person" ? SHORT_SETUP_NOTICE : reader === "verb" && await claimFullSetupNotice() ? step.markdown : SETUP_NUDGE;
     process.stderr.write(`
-${SHORT_SETUP_NOTICE}
+${text}
 
 `);
     return;
@@ -22912,8 +24195,8 @@ function makeParseErrorsActionable(program) {
   const decorate = (cmd) => {
     cmd.showSuggestionAfterError(true);
     cmd.configureOutput({
-      outputError: (str, write) => {
-        write(str);
+      outputError: (str, write2) => {
+        write2(str);
         if (!/unknown option|unknown command|too many arguments/i.test(str)) return;
         const names = [];
         for (let node = cmd; node !== null; node = node.parent) {
@@ -22922,12 +24205,12 @@ function makeParseErrorsActionable(program) {
         const path = names.join(" ");
         const runnable = cmd.commands.filter((sub) => sub._hidden !== true).map((sub) => sub.name()).sort();
         if (/unknown command/i.test(str) && runnable.length > 0) {
-          write(`hint: ${path} has ${runnable.join(" ")}
+          write2(`hint: ${path} has ${runnable.join(" ")}
 `);
           return;
         }
         const flags = cmd.options.map((o) => o.long ?? o.short).filter(Boolean);
-        write(
+        write2(
           flags.length > 0 ? `hint: ${path} takes ${flags.join(" ")}
 ` : `hint: \`${path} --help\` lists what this takes.
 `
@@ -22954,10 +24237,13 @@ async function run3(argv) {
         return;
       }
     }
-    await announceNextStep("", process.stderr.isTTY === true);
+    await announceNextStep(
+      "",
+      process.stderr.isTTY === true ? "person" : cleaned[2] === void 0 ? "full" : "brief"
+    );
   }
   await program.parseAsync(cleaned);
-  if (argv[2] !== "update") await backgroundUpdateNotice();
+  if (argv[2] !== "update") await backgroundUpdateNotice(argv[2] === void 0 ? {} : { verb: argv[2] });
 }
 async function handleError(err) {
   const failure = adaptRegistryError(err) ?? err;