@rayul/kordis 0.15.1 → 0.16.0

package/dist/index.js

@@ -134,12 +134,32 @@ var init_enums = __esm({
   }
 });
 
+// ../../packages/contracts/src/refresh-race.ts
+function isRefreshRace(body) {
+  if (typeof body !== "object" || body === null) return false;
+  const error = body.error;
+  if (typeof error !== "object" || error === null) return false;
+  const { code, flags } = error;
+  if (code !== "not_authenticated" || !Array.isArray(flags)) return false;
+  return flags.some(
+    (flag2) => typeof flag2 === "object" && flag2 !== null && flag2.code === REFRESH_RACE_FLAG
+  );
+}
+var REFRESH_RACE_FLAG;
+var init_refresh_race = __esm({
+  "../../packages/contracts/src/refresh-race.ts"() {
+    "use strict";
+    REFRESH_RACE_FLAG = "refresh_rotated_by_another_request";
+  }
+});
+
 // ../../packages/contracts/src/errors.ts
 import { z as z3 } from "zod";
 var ErrorCodeSchema, ERROR_EXIT_CODES, ReviewFlagSchema, ApiErrorSchema;
 var init_errors = __esm({
   "../../packages/contracts/src/errors.ts"() {
     "use strict";
+    init_refresh_race();
     ErrorCodeSchema = z3.enum([
       "generic_failure",
       // 1
@@ -1159,16 +1179,33 @@ var init_api = __esm({
        */
       content: z11.string().min(50).max(1e5),
       /**
-       * Inline overrides for frontmatter fields. Merged into parsed frontmatter
-       * server-side; existing frontmatter wins if both present.
+       * Optional, and refused when it disagrees. core-api stores the title,
+       * description and type it reads from the frontmatter of `content`, which must
+       * carry all three (the title may come from `name:`). A value here that
+       * differs from the frontmatter's, compared trimmed, is refused as
+       * `usage_error` (HTTP 400) with a hint naming the frontmatter key; absent
+       * means no claim. A `type` the registry cannot publish at all (`scoped-rule`,
+       * `mdc-rule`, `plugin`) names no key to write: its hint says the type cannot
+       * be published yet and to drop `--type`. `kordis push` ≤0.15.2 sends
+       * `--type` here, and writes `type: skill` into the frontmatter of a SKILL.md
+       * or *.skill.md file, a folder or a .skill bundle that names no type — so
+       * `--type hook` on one is refused, where until 2026-10 it published a skill.
+       * Later versions send no `type`: they write `--type` into the frontmatter.
        */
       title: z11.string().min(1).max(200).optional(),
       description: z11.string().min(1).max(2048).optional(),
       type: HarnessTypeSchema.optional(),
+      /**
+       * A new package is published under this slug instead of the one derived from
+       * the frontmatter title. An update keeps the slug of the package it updates:
+       * a slug here that differs from the target's is refused (`usage_error`).
+       */
       slug: SlugSchema.optional(),
       /**
-       * When updating, the target full_slug. Omitted for new packages (server
-       * derives slug from title or accepts inline `slug`).
+       * When updating, the target full_slug; its presence is what makes a publish
+       * an update (`PUT /api/packages/:u/:s` sets it from the path). Omitted for a
+       * new package, whose slug is `slug` or else derived from the frontmatter
+       * title — never derived on an update.
        */
       target_full_slug: FullSlugSchema.optional(),
       /**
@@ -1176,6 +1213,12 @@ var init_api = __esm({
        */
       bump: z11.enum(["patch", "minor", "major"]).optional(),
       changelog: z11.string().max(2e3).optional(),
+      /**
+       * Refused when non-empty (`usage_error`): a package's dependencies are read
+       * from its frontmatter's `depends:` and `recommends:` lists only. Kept in the
+       * schema so the server sees them to refuse them — this object is non-strict,
+       * and an unlisted key would be stripped without a word.
+       */
       depends: z11.array(z11.string()).optional(),
       recommends: z11.array(z11.string()).optional(),
       /**
@@ -1675,9 +1718,122 @@ var init_telemetry = __esm({
 });
 
 // ../../packages/contracts/src/review-patterns.ts
+var STAGE_1_REJECT_PATTERNS, STAGE_1_5_AUP_PATTERNS, DETERMINISTIC_REJECT_PATTERNS;
 var init_review_patterns = __esm({
   "../../packages/contracts/src/review-patterns.ts"() {
     "use strict";
+    STAGE_1_REJECT_PATTERNS = [
+      {
+        code: "curl_pipe_shell",
+        pattern: /\bcurl\s+[^|;]+\s*\|\s*(?:(?:sudo|doas)\s+)?(?:-E\s+|[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(?:sh|bash|zsh|ksh|dash|csh|tcsh|fish)\b/i,
+        hint: "Replace `curl \u2026 | bash` with a verifiable install path: download the script to a file, show the user `cat` of it for inspection, then `bash <file>` only after confirmation."
+      },
+      {
+        code: "wget_pipe_shell",
+        pattern: /\bwget\s+[^|;]+\s*\|\s*(?:(?:sudo|doas)\s+)?(?:-E\s+|[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(?:sh|bash|zsh|ksh|dash|csh|tcsh|fish)\b/i,
+        hint: "Replace `wget \u2026 | bash` with a verifiable install path: download the script to a file, show the user `cat` of it for inspection, then `bash <file>` only after confirmation."
+      },
+      {
+        code: "shell_process_substitution",
+        pattern: /(?:bash|sh|zsh)\s*<\(\s*(?:curl|wget)\b/i,
+        hint: "Replace `bash <(curl \u2026)` with a verifiable install path: download the script to a file, show the user `cat` of it for inspection, then `bash <file>` only after confirmation."
+      },
+      {
+        code: "eval_atob",
+        pattern: /\beval\s*\(\s*atob\b/i,
+        hint: "Encoded eval (`eval(atob(...))`) is a hallmark of obfuscated payloads. Move the logic into plain code the reader can audit."
+      },
+      {
+        code: "eval_buffer_from",
+        pattern: /\beval\s*\(\s*Buffer\.from\b/i,
+        hint: "Encoded eval (`eval(Buffer.from(...))`) is a hallmark of obfuscated payloads. Move the logic into plain code the reader can audit."
+      },
+      {
+        code: "aws_access_key",
+        pattern: /\b(?:AKIA|ASIA|AGPA)[0-9A-Z]{16}\b/,
+        hint: "Remove the AWS access key from the body. Reference credentials via env var (`AWS_ACCESS_KEY_ID`); rotate the leaked key immediately if it was real."
+      },
+      {
+        code: "private_key_block",
+        pattern: /-----BEGIN\s+(?:[A-Z0-9]+\s+)?PRIVATE\s+KEY(?:\s+BLOCK)?-----/,
+        hint: "Remove the private key block from the body. Reference keys via env var or a secret manager; rotate the leaked key immediately if it was real."
+      },
+      {
+        code: "google_api_key",
+        pattern: /\bAIza[0-9A-Za-z_-]{35}\b/,
+        hint: "Remove the Google API key from the body. Reference credentials via env var; rotate the leaked key immediately if it was real."
+      },
+      {
+        code: "slack_token",
+        pattern: /\b(?:xox[abpors]|xapp|xoxe)-[0-9a-zA-Z-]{10,}\b/,
+        hint: "Remove the Slack token from the body. Reference tokens via env var; revoke the leaked token immediately if it was real."
+      },
+      {
+        code: "github_token",
+        pattern: /\b(?:gh[pousr]_[A-Za-z0-9_]{36,}|github_pat_[A-Za-z0-9_]{60,})\b/,
+        hint: "Remove the GitHub token from the body. Reference tokens via env var; revoke the leaked token immediately if it was real."
+      }
+    ];
+    STAGE_1_5_AUP_PATTERNS = [
+      {
+        // Stolen-card / bank-credential trafficking storefronts. Anchored to the
+        // trafficking jargon that only appears in carding markets, not in the
+        // defensive "how to detect carding" literature. `dumps` is also an
+        // ordinary developer verb — "this hook dumps vendor files", "dumps store
+        // state", "dumps market data to CSV" all matched the shared noun list —
+        // so after `dumps` only sale framing (`shop`, `for sale`) counts, while
+        // `cvv` and `fullz` keep the full list. Narrowed when comments started
+        // running this table (2026-10-14).
+        code: "aup_stolen_financial_data_market",
+        pattern: /\b(?:cvv|fullz)\s+(?:shop|store|for\s+sale|market|vendor)\b|\bdumps\s+(?:shop|for\s+sale)\b|\bdumps?\s+with\s+pin\b|\bsell(?:ing)?\s+(?:cvv|fullz|dumps)\b/i,
+        hint: "This reads as a storefront for trafficking stolen financial data, which violates the Kordis AUP. If the package is about DETECTING or DEFENDING against card fraud, reword it so it does not read as an offer to buy/sell stolen data."
+      },
+      {
+        // DDoS-for-hire (booter/stresser) services sold on a subscription.
+        code: "aup_ddos_for_hire",
+        pattern: /\b(?:booter|stresser)\s+(?:service|panel|subscription)\b|\b(?:ddos|dstat)\s+for\s+hire\b|\bhire\s+(?:a\s+)?(?:booter|stresser|ddos)\b/i,
+        hint: "This reads as a DDoS-for-hire (booter/stresser) service, which violates the Kordis AUP. Load-testing tooling is fine \u2014 describe it as testing infrastructure you own/are authorized to test, not a for-hire attack service."
+      },
+      {
+        // Malware/stealer/ransomware sold or distributed as a product ("builder
+        // for sale", "buy our stealer"). A skill that DEFENDS against these, or a
+        // malware-analysis skill, does not use buy/sell framing.
+        code: "aup_malware_sale",
+        pattern: /\b(?:ransomware|stealer|infostealer|rat|keylogger|botnet)\s+(?:builder|kit|panel|source)\s+(?:for\s+sale|for\s+rent)\b|\b(?:buy|sell(?:ing)?|rent)\s+(?:our\s+)?(?:ransomware|stealer|infostealer|botnet)\b/i,
+        hint: "This reads as an offer to sell/rent malware, which violates the Kordis AUP. Malware ANALYSIS and DEFENSE content is welcome \u2014 reword so it does not read as distributing a weaponized build."
+      },
+      {
+        // Child sexual abuse material. Unlike the rest of this table this entry is
+        // NOT anchored to solicitation: it matches the spelled-out phrases ("child
+        // porn", "child pornography", "child sexual abuse material") wherever they
+        // appear, child-safety and moderation education included. Only the
+        // acronym "CSAM" on its own does not match ("how platforms detect CSAM
+        // for NCMEC reporting" passes). Kept this broad on purpose (2026-10-14):
+        // comments have no Stage-2 review after this table, so a miss costs more
+        // than a false positive.
+        code: "aup_csam",
+        pattern: /\bchild\s+(?:porn(?:ography)?|sexual\s+abuse\s+material)\b/i,
+        hint: "This reads as solicitation or distribution of child sexual abuse material, which is illegal and violates the Kordis AUP. This is a terminal, non-appealable rejection."
+      },
+      {
+        // Drug / untraceable-weapon brokering with explicit no-id / untraceable /
+        // dark-web fulfillment language — not a bare mention of a substance or
+        // firearm topic (e.g. harm-reduction or policy content does not use this
+        // buy/sell + untraceable-fulfillment framing together).
+        code: "aup_drug_weapon_brokering",
+        pattern: /\b(?:buy|sell(?:ing)?)\b[\s\S]{0,40}\b(?:cocaine|heroin|fentanyl|methamphetamine|untraceable firearms?|untraceable guns?)\b[\s\S]{0,40}\b(?:no id|untraceable|worldwide shipping|dark ?web)\b/i,
+        hint: "This reads as brokering illegal drugs or untraceable weapons for sale, which violates the Kordis AUP. If the package is about DETECTING or REPORTING such activity, reword it so it does not read as an offer to buy/sell."
+      },
+      {
+        // A directive to dox or swat a specific, named/tagged target — not a
+        // bare mention of doxxing/swatting as a topic (e.g. "how to protect
+        // yourself from doxxing" does not match).
+        code: "aup_targeted_harassment_directive",
+        pattern: /\b(?:dox|swat)\s+(?:this (?:guy|girl|person|user)|him|her|@[\w.]+)\b/i,
+        hint: "This reads as a directive to dox or swat a specific target, which violates the Kordis AUP. Remove the targeted-harassment instruction."
+      }
+    ];
+    DETERMINISTIC_REJECT_PATTERNS = [...STAGE_1_REJECT_PATTERNS, ...STAGE_1_5_AUP_PATTERNS];
   }
 });
 
@@ -2443,13 +2599,17 @@ var init_sections = __esm({
 
 // ../../packages/memory-engine/src/schema.ts
 import { z as z22 } from "zod";
-var MappingModeSchema, ScopeSourceSchema, SCOPE_LIMIT, TELEMETRY_ERROR_KINDS, TELEMETRY_MESSAGE_LIMIT, TelemetryErrorPayloadSchema2, ProvenanceSchema, MemoryStatusSchema, ClaimConfidenceSchema, MemoryKindSchema, ClaimSchema, MemorySchema, RelationTypeSchema, RelationSourceSchema, RelationSchema;
+function isGlobalScope(scope) {
+  return scope != null && scope.trim().toLowerCase() === GLOBAL_SCOPE;
+}
+var MappingModeSchema, ScopeSourceSchema, SCOPE_LIMIT, GLOBAL_SCOPE, TELEMETRY_ERROR_KINDS, TELEMETRY_MESSAGE_LIMIT, TelemetryErrorPayloadSchema2, ProvenanceSchema, MemoryStatusSchema, ClaimConfidenceSchema, MemoryKindSchema, ClaimSchema, MemorySchema, RelationTypeSchema, RelationSourceSchema, RelationSchema;
 var init_schema = __esm({
   "../../packages/memory-engine/src/schema.ts"() {
     "use strict";
     MappingModeSchema = z22.enum(["explicit", "heuristic"]);
     ScopeSourceSchema = z22.enum(["explicit", "path", "none"]);
     SCOPE_LIMIT = 128;
+    GLOBAL_SCOPE = "global";
     TELEMETRY_ERROR_KINDS = [
       "network_unreachable",
       "server_error",
@@ -2529,6 +2689,26 @@ var init_schema = __esm({
       scope: z22.string().min(1).nullable(),
       /** Id of the claim that is current for this memory, when one is declared. */
       current_claim: z22.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: z22.string().min(1).optional(),
       status: MemoryStatusSchema,
       /**
        * Whether this memory binds what an agent does, rather than informing it.
@@ -2610,6 +2790,104 @@ var init_schema = __esm({
   }
 });
 
+// ../../packages/memory-engine/src/layout.ts
+var OBSERVATIONS_DIR, DERIVED_DIR, DERIVED_BLUEPRINT;
+var init_layout = __esm({
+  "../../packages/memory-engine/src/layout.ts"() {
+    "use strict";
+    OBSERVATIONS_DIR = "_observations";
+    DERIVED_DIR = "_derived";
+    DERIVED_BLUEPRINT = "_blueprint.json";
+  }
+});
+
+// ../../packages/memory-engine/src/rule-budget.ts
+function ruleLane(scope, project) {
+  if (scope == null || scope.trim() === "" || isGlobalScope(scope)) return "global";
+  if (project === null) return "elsewhere";
+  return scope.trim().toLowerCase() === project.trim().toLowerCase() ? "project" : "elsewhere";
+}
+function declaredScopeOf(memory) {
+  return memory.provenance.scopeSource === "explicit" ? memory.scope : null;
+}
+function splitRuleBudget(ranked, scopeOf, project, budget = DEFAULT_RULE_BUDGET) {
+  const globalLane = [];
+  const projectLane = [];
+  const elsewhere = [];
+  for (const item of ranked) {
+    const lane = ruleLane(scopeOf(item), project);
+    if (lane === "global") globalLane.push(item);
+    else if (lane === "project") projectLane.push(item);
+    else elsewhere.push(item);
+  }
+  const total = budget.global + budget.project;
+  const globalRoom = Math.max(budget.global, total - Math.min(projectLane.length, budget.project));
+  const projectRoom = Math.max(budget.project, total - Math.min(globalLane.length, budget.global));
+  return {
+    global: globalLane.slice(0, globalRoom),
+    project: projectLane.slice(0, projectRoom),
+    elsewhere,
+    // Everything either budget COULD have shown, so "5 of 12" is honest about
+    // the cap without counting another project's rules as things withheld.
+    eligible: globalLane.length + projectLane.length
+  };
+}
+var DEFAULT_RULE_BUDGET;
+var init_rule_budget = __esm({
+  "../../packages/memory-engine/src/rule-budget.ts"() {
+    "use strict";
+    init_schema();
+    DEFAULT_RULE_BUDGET = { global: 5, project: 5 };
+  }
+});
+
+// ../../packages/memory-engine/src/rule-text.ts
+function ruleTextOf(entry) {
+  const intro = (entry.chunks ?? []).find((chunk) => chunk.label === null)?.text.trim();
+  if (intro !== void 0 && intro !== "") return intro;
+  return entry.memory.summary ?? entry.memory.title;
+}
+function ruleWidthFor(count) {
+  if (count <= 0) return RULE_WIDTH_MIN;
+  const share = Math.floor(RULE_BLOCK_BUDGET / count);
+  return Math.min(RULE_WIDTH_MAX, Math.max(RULE_WIDTH_MIN, share));
+}
+function rulePassage(text, max) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  const chars = [...flat];
+  if (chars.length <= max) return flat;
+  if (max <= 1) return "\u2026";
+  const budget = max - 1;
+  if (budget < 2) return `${chars.slice(0, budget).join("")}\u2026`;
+  const tailBudget = Math.min(budget - 1, Math.max(1, Math.floor(budget * 0.6)));
+  const tail = [...trailingSentences(flat, tailBudget)];
+  const head = chars.slice(0, budget - tail.length).join("").trimEnd();
+  return `${head}\u2026${tail.join("")}`;
+}
+function trailingSentences(flat, budget) {
+  const starts = [...flat.matchAll(/[.!?。！？](?=\s)/g)].map(
+    (match) => match.index + match[0].length
+  );
+  let best = null;
+  for (let i = starts.length - 1; i >= 0; i -= 1) {
+    const candidate = flat.slice(starts[i]).trim();
+    if ([...candidate].length > budget) break;
+    if (candidate !== "") best = candidate;
+  }
+  if (best !== null) return best;
+  return [...flat].slice(-budget).join("");
+}
+var RULE_WIRE_WIDTH, RULE_WIDTH_MIN, RULE_WIDTH_MAX, RULE_BLOCK_BUDGET;
+var init_rule_text = __esm({
+  "../../packages/memory-engine/src/rule-text.ts"() {
+    "use strict";
+    RULE_WIRE_WIDTH = 600;
+    RULE_WIDTH_MIN = 200;
+    RULE_WIDTH_MAX = 600;
+    RULE_BLOCK_BUDGET = RULE_WIDTH_MIN * 10;
+  }
+});
+
 // ../../packages/memory-engine/src/boundary.ts
 function normalizeForMatch(value) {
   return value.normalize("NFC").replace(ZERO_WIDTH, "").replace(WHITESPACE_RUN, " ").trim();
@@ -2753,8 +3031,8 @@ function scopeFromPath(path2) {
   return parts.length >= 2 ? parts[parts.length - 2] ?? null : null;
 }
 function titleFromPath(path2) {
-  const base = path2.split("/").pop() ?? path2;
-  return base.replace(/\.[^.]+$/, "") || base;
+  const base2 = path2.split("/").pop() ?? path2;
+  return base2.replace(/\.[^.]+$/, "") || base2;
 }
 function h1Of(intro) {
   for (const line of intro.split("\n")) {
@@ -2868,8 +3146,8 @@ function mapNoteToMemory(input) {
   const ns = explicit ? nsRaw : {};
   const id = asString(ns["id"]) ?? path2;
   const title = asString(ns["title"]) ?? asString(frontmatter?.["title"]) ?? h1Of(outline.intro) ?? titleFromPath(path2);
-  const declaredScope = asString(ns["scope"]);
-  const scope = declaredScope ?? scopeFromPath(path2);
+  const declaredScope2 = asString(ns["scope"]);
+  const scope = declaredScope2 ?? scopeFromPath(path2);
   const summary = asString(ns["summary"]) ?? outline.description ?? firstParagraph(outline.intro) ?? firstSectionParagraph(outline.sections) ?? null;
   const memory = {
     id,
@@ -2913,11 +3191,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: path2,
       sourceRevision: revision,
       mapping: explicit ? "explicit" : "heuristic",
-      scopeSource: declaredScope !== null ? "explicit" : scope === null ? "none" : "path"
+      scopeSource: declaredScope2 !== null ? "explicit" : scope === null ? "none" : "path"
     }
   };
   const claims = [];
@@ -2943,22 +3227,6 @@ function mapNoteToMemory(input) {
     issues
   };
 }
-function isUntouchedBase(path2, content) {
-  if (!/^01_BASE\//.test(path2)) return false;
-  const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---[ \t]*(\r?\n|$)/, "");
-  const lines = body.split(/\r?\n/).map((l) => l.trimEnd());
-  let seenHeading = false;
-  for (const line of lines) {
-    if (line.trim() === "") continue;
-    if (!seenHeading && line.startsWith("# ")) {
-      seenHeading = true;
-      continue;
-    }
-    if (/^-\s*$/.test(line)) continue;
-    if (/^[-*+]\s+\S/.test(line) || /^#{1,6}\s/.test(line)) return false;
-  }
-  return seenHeading;
-}
 var NAMESPACE, isRecord, asString, asStringArray, AUTHORABLE;
 var init_markdown_mapping = __esm({
   "../../packages/memory-engine/src/markdown-mapping.ts"() {
@@ -3048,7 +3316,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 = z23.object({
       path: z23.string().min(1),
@@ -3663,6 +3931,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];
@@ -3735,8 +4009,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);
@@ -3744,13 +4019,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";
@@ -3759,6 +4034,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",
@@ -3909,7 +4298,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";
@@ -3939,7 +4328,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) {
@@ -3949,6 +4354,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);
@@ -4049,7 +4462,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 };
+      })()
     };
   }
 }
@@ -4080,7 +4497,7 @@ function resolveDetail(entries, handle) {
   const entry = entries.find((e) => e.memory.id === id);
   return entry ? { memory: entry.memory, claims: entry.claims, relations: entry.relations } : null;
 }
-var RECALL_DEPTHS, RecallOptionError, SEMANTIC_CANDIDATES, 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, SEMANTIC_CANDIDATES, 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";
@@ -4089,6 +4506,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;
@@ -4175,18 +4593,164 @@ var init_planner = __esm({
   }
 });
 
+// ../../packages/memory-engine/src/note-body.ts
+function bodyOf(content) {
+  const stripped = content.startsWith(BOM) ? content.slice(BOM.length) : content;
+  const fence2 = FENCE.exec(stripped);
+  return fence2 ? stripped.slice(fence2[0].length) : stripped;
+}
+var BOM, FENCE;
+var init_note_body = __esm({
+  "../../packages/memory-engine/src/note-body.ts"() {
+    "use strict";
+    BOM = String.fromCharCode(65279);
+    FENCE = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(\r?\n|$)/;
+  }
+});
+
+// ../../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;
+}
+function wordingsFor(path2) {
+  const current = ownEntry(BASE_TEMPLATES, path2);
+  const retired = ownEntry(RETIRED_BASE_TEMPLATES, path2) ?? [];
+  return current === void 0 ? retired : [current, ...retired];
+}
+function isExactUntouchedBase(path2, content) {
+  const saved = asSaved(content);
+  return wordingsFor(path2).some((t) => asSaved(t) === saved);
+}
+function isTemplateBody(path2, content) {
+  const lines = bodyLines(content).join("\n");
+  return wordingsFor(path2).some((t) => bodyLines(t).join("\n") === lines);
+}
+function isUnwrittenBody(path2, content) {
+  if (isTemplateBody(path2, content)) return true;
+  const [first, ...rest] = bodyLines(content);
+  if (first === void 0) return false;
+  const headings = wordingsFor(path2).map((t) => bodyLines(t)[0]);
+  return headings.includes(first) && rest.every((line) => /^-\s*$/.test(line));
+}
+var BASE_TEMPLATES, RETIRED_BASE_TEMPLATES, BOM2, asSaved, bodyLines;
+var init_base_templates = __esm({
+  "../../packages/memory-engine/src/base-templates.ts"() {
+    "use strict";
+    init_note_body();
+    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")
+      ]
+    };
+    BOM2 = String.fromCharCode(65279);
+    asSaved = (text) => (text.startsWith(BOM2) ? text.slice(BOM2.length) : text).replace(/\r\n/g, "\n").trimEnd();
+    bodyLines = (content) => bodyOf(content).split("\n").map((line) => line.trimEnd()).filter((line) => line.trim() !== "");
+  }
+});
+
 // ../../packages/memory-engine/src/recall/semantic.ts
-function withoutUntouchedBase(hits, contentById) {
+function withoutUntouchedBase(hits, contentById, isTemplate = isExactUntouchedBase) {
   return hits.filter((hit) => {
     const note = contentById.get(hit.id);
-    return note === void 0 ? true : !isUntouchedBase(note.path, note.content);
+    return note === void 0 ? true : !isTemplate(note.path, note.content);
   });
 }
 var SEMANTIC_FIELDS;
 var init_semantic = __esm({
   "../../packages/memory-engine/src/recall/semantic.ts"() {
     "use strict";
-    init_markdown_mapping();
+    init_base_templates();
     SEMANTIC_FIELDS = {
       /** `used` or `skipped`. Always present on a server that has this at all. */
       state: "semantic",
@@ -4200,6 +4764,103 @@ var init_semantic = __esm({
   }
 });
 
+// ../../packages/memory-engine/src/recall/unfilled.ts
+function markUnfilled(cards, contentById, slots, inConflict = /* @__PURE__ */ new Set()) {
+  const kept = [];
+  const withheld = [];
+  let templates = 0;
+  for (const card of cards) {
+    const note = contentById.get(card.id);
+    const unfilled = note !== void 0 && isExactUntouchedBase(note.path, note.content);
+    if (unfilled && slots !== void 0 && !inConflict.has(card.id) && ++templates > slots) {
+      withheld.push(card.id);
+      continue;
+    }
+    kept.push({ ...card, unfilled });
+  }
+  return { cards: kept, withheld };
+}
+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/setup-progress.ts
+var SETUP_PROGRESS_CODES;
+var init_setup_progress = __esm({
+  "../../packages/memory-engine/src/setup-progress.ts"() {
+    "use strict";
+    SETUP_PROGRESS_CODES = [
+      /** Installing the guidance and settings. */
+      "writing_config",
+      /** Uploading the chosen folder's notes. */
+      "uploading",
+      /** An upload chosen on the screen, held until somebody at the terminal checks the account. */
+      "upload_waits_for_check",
+      /** Finished. */
+      "done",
+      /** This machine is signed in to a different account; nothing was changed. */
+      "different_account",
+      /** Failed for another reason; `detail` says which. */
+      "failed"
+    ];
+  }
+});
+
+// ../../packages/memory-engine/src/recall/query-prefix.ts
+var QUERY_EMBEDDING_PREFIX;
+var init_query_prefix = __esm({
+  "../../packages/memory-engine/src/recall/query-prefix.ts"() {
+    "use strict";
+    QUERY_EMBEDDING_PREFIX = "task: search result | query: ";
+  }
+});
+
+// ../../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 SCOPE_SPREAD_FIELD, ELSEWHERE_SHOWN;
+var init_scope_spread = __esm({
+  "../../packages/memory-engine/src/recall/scope-spread.ts"() {
+    "use strict";
+    SCOPE_SPREAD_FIELD = "scope_spread";
+    ELSEWHERE_SHOWN = 5;
+  }
+});
+
 // ../../packages/memory-engine/src/proposal/schema.ts
 import { z as z24 } from "zod";
 function isLifecycleAction(action) {
@@ -4208,8 +4869,17 @@ function isLifecycleAction(action) {
 function isClassifyAction(action) {
   return action === "reclassify";
 }
+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);
+  return isLifecycleAction(action) || isClassifyAction(action) || isBindingAction(action) || isScopeAction(action) || isValidityAction(action);
 }
 function isAccepted(value) {
   return typeof value === "object" && value !== null && value[ACCEPTED] === true;
@@ -4238,6 +4908,47 @@ var init_schema2 = __esm({
       "retire",
       "unretire",
       "reclassify",
+      /**
+       * A memory stops binding. Nothing else about it changes.
+       *
+       * It exists because there was no way to do this without saying something
+       * else. Taking a marking back meant `revise --claim`, which is a verb about
+       * conclusions — so unbinding thirteen rules on a real hosted brain required
+       * restating thirteen conclusions the author had not changed, from text the
+       * CLI hands back TRUNCATED. The person doing it read the note bodies out of
+       * the database to avoid corrupting them, which is not a thing a user can do.
+       *
+       * One direction on purpose. `unbind` that could also bind would be a name
+       * that lies half the time; marking something as a rule is already reachable
+       * (`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"]);
@@ -4397,6 +5108,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: z24.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: z24.string().min(1).nullable().default(null),
       relations: ProposedRelationsSchema,
       /** Why the AI thinks this change is right. Shown at approval time. */
       reason: z24.string().min(1),
@@ -4433,7 +5175,7 @@ var init_schema2 = __esm({
         path: ["source_excerpt"]
       }
     ).refine((p) => carriesNoClaim(p.action) || p.claim !== null, {
-      message: "only retire, unretire and reclassify 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",
@@ -4441,6 +5183,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");
   }
@@ -4490,12 +5244,42 @@ function detectConsolidation(entries, opts = {}) {
     ...titles
   ];
   const out = rankCandidates(scored);
+  const limit = opts.limit ?? DEFAULT_LIMIT;
   return {
-    candidates: out.slice(0, opts.limit ?? DEFAULT_LIMIT),
+    candidates: shareTheList(out, limit),
+    by_rule: countByRule(out),
     scanned: budget.scanned,
     truncated: budget.truncated
   };
 }
+function shareTheList(ranked, limit) {
+  const lanes = /* @__PURE__ */ new Map();
+  for (const candidate of ranked) {
+    const lane = lanes.get(candidate.rule);
+    if (lane) lane.push(candidate);
+    else lanes.set(candidate.rule, [candidate]);
+  }
+  const out = [];
+  const queues = [...lanes.values()];
+  let round = 0;
+  for (; ; ) {
+    let added = false;
+    for (const queue of queues) {
+      if (out.length >= limit) return out;
+      const next = queue[round];
+      if (next === void 0) continue;
+      out.push(next);
+      added = true;
+    }
+    if (!added) return out;
+    round += 1;
+  }
+}
+function countByRule(ranked) {
+  const out = {};
+  for (const candidate of ranked) out[candidate.rule] = (out[candidate.rule] ?? 0) + 1;
+  return out;
+}
 function titleTerms(title) {
   const out = /* @__PURE__ */ new Set();
   for (const term of terms(title)) {
@@ -4843,19 +5627,38 @@ function kindPromotions(entries) {
   const out = [];
   for (const entry of entries) {
     if (entry.memory.binding !== true) continue;
-    if (entry.memory.kind === "decision") continue;
+    const kind = entry.memory.kind;
+    if (kind !== void 0 && RULE_SHAPED_KINDS.has(kind)) continue;
+    if (kind === void 0) {
+      out.push({
+        candidate: {
+          rule: "binding_unclassified",
+          memory_id: entry.memory.id,
+          path: entry.path,
+          title: entry.memory.title,
+          other_id: null,
+          other_path: null,
+          other_title: null,
+          evidence: "marked as binding and left unclassified \u2014 either a decision nobody classified, or something that was never a rule",
+          suggested_action: "decide",
+          suggested_kind: null
+        },
+        confidence: 4
+      });
+      continue;
+    }
     out.push({
       candidate: {
-        rule: "kind_promotion",
+        rule: "rule_demotion",
         memory_id: entry.memory.id,
         path: entry.path,
         title: entry.memory.title,
         other_id: null,
         other_path: null,
         other_title: null,
-        evidence: entry.memory.kind === void 0 ? "marked as binding but left unclassified \u2014 a memory that binds is a decision" : `marked as binding but classified as ${entry.memory.kind} \u2014 a memory that binds is a decision`,
-        suggested_action: "reclassify",
-        suggested_kind: "decision"
+        evidence: `marked as binding but classified as ${kind} \u2014 the author said it is not a decision, so it may not be a rule`,
+        suggested_action: "unmark_rule",
+        suggested_kind: null
       },
       confidence: 4
     });
@@ -4962,7 +5765,7 @@ function* pairsFrom(buckets, budget) {
     }
   }
 }
-var CONSOLIDATION_RULES, DEFAULT_LIMIT, DEFAULT_PAIR_BUDGET, SEMANTIC_PAIR_BUDGET, TITLE_OVERLAP, SAME_SCOPE_SEMANTIC_SIMILARITY, SHARED_ENTITY_SEMANTIC_SIMILARITY, GLOBAL_SEMANTIC_SIMILARITY, RECIPROCAL_NEIGHBOURS, CandidateComponents;
+var CONSOLIDATION_RULES, DEFAULT_LIMIT, DEFAULT_PAIR_BUDGET, SEMANTIC_PAIR_BUDGET, TITLE_OVERLAP, SAME_SCOPE_SEMANTIC_SIMILARITY, SHARED_ENTITY_SEMANTIC_SIMILARITY, GLOBAL_SEMANTIC_SIMILARITY, RECIPROCAL_NEIGHBOURS, RULE_SHAPED_KINDS, CandidateComponents;
 var init_detect = __esm({
   "../../packages/memory-engine/src/proposal/detect.ts"() {
     "use strict";
@@ -4973,7 +5776,9 @@ var init_detect = __esm({
       "semantic_similarity",
       "shared_context",
       "similar_title",
-      "kind_promotion"
+      "kind_promotion",
+      "rule_demotion",
+      "binding_unclassified"
     ];
     DEFAULT_LIMIT = 50;
     DEFAULT_PAIR_BUDGET = 2e5;
@@ -4983,6 +5788,7 @@ var init_detect = __esm({
     SHARED_ENTITY_SEMANTIC_SIMILARITY = 0.75;
     GLOBAL_SEMANTIC_SIMILARITY = 0.72;
     RECIPROCAL_NEIGHBOURS = 2;
+    RULE_SHAPED_KINDS = /* @__PURE__ */ new Set(["decision", "preference"]);
     CandidateComponents = class {
       parent = /* @__PURE__ */ new Map();
       root(id) {
@@ -5319,12 +6125,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.` : `${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 and reclassify may omit it. They change a memory's standing or its classification 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`), {
@@ -5341,6 +6147,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 = {
@@ -5350,6 +6176,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,
@@ -5380,14 +6208,22 @@ var init_commit = __esm({
        */
       memory_id: z26.string().min(1).nullable().default(null),
       /**
-       * Omitted by `retire` / `unretire` / `reclassify`, which change a memory's
-       * standing or its classification rather than what it says. Checked below with
-       * the other action rules so the error can name the action instead of pointing
-       * at a field.
+       * Omitted by `retire` / `unretire` / `reclassify` / `unbind`, which change a
+       * memory's standing, its classification or whether it binds — rather than
+       * what it says. Checked below with the other action rules so the error can
+       * name the action instead of pointing at a field.
        */
       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: z26.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: z26.string().min(1).nullable().default(null),
       relations: ProposedRelationsSchema.default({}),
       reason: z26.string().min(1),
       /** The passage from the note that justifies this. Required to submit. */
@@ -5488,6 +6324,68 @@ function reclassifyInput(entry, kind, opts = {}) {
     target_path: entry.path
   };
 }
+function unbindInput(entry, opts = {}) {
+  return {
+    action: "unbind",
+    memory_id: entry.memory.id,
+    claim: null,
+    reason: opts.reason ?? "no longer binding",
+    source_excerpt: opts.because ?? entry.memory.summary ?? entry.memory.title,
+    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;
@@ -5495,6 +6393,7 @@ function saysNothingNew(entry, input, normalize) {
   if (norm(claim.text) !== norm(previousClaim(entry))) return false;
   if (claim.summary != null && norm(claim.summary) !== norm(entry.memory.summary)) return false;
   if (claim.title != null && norm(claim.title) !== norm(entry.memory.title)) return false;
+  if (claim.binding != null && claim.binding !== (entry.memory.binding === true)) return false;
   const declared = new Set(
     entry.relations.filter((r) => r.type === "contradicts").map((r) => r.to)
   );
@@ -5507,11 +6406,6 @@ function bodyStillAsserts(content, oldClaim, newClaim, normalize) {
   if (line === normalize(newClaim?.split("\n")[0] ?? "").trim()) return null;
   return bodyOf(content).includes(line) ? line : null;
 }
-function bodyOf(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;
-}
 function previousClaim(entry) {
   const current = entry.claims.find((claim) => claim.id === entry.memory.current_claim) ?? entry.claims[0];
   return current?.text ?? null;
@@ -5527,6 +6421,9 @@ var init_curate = __esm({
   "../../packages/memory-engine/src/capture/curate.ts"() {
     "use strict";
     init_planner();
+    init_schema();
+    init_rule_budget();
+    init_note_body();
     NO_REASON_GIVEN = "revised directly";
     noLifecycleReason = (action) => `${action}d directly`;
   }
@@ -5577,6 +6474,25 @@ function desiredFields(proposal, existing) {
     out["kind"] = proposal.proposed_kind;
     return out;
   }
+  if (isBindingAction(proposal.action)) {
+    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`);
@@ -5874,6 +6790,108 @@ function verifyPatch(patched, proposal, before) {
     }
     return;
   }
+  if (isBindingAction(proposal.action)) {
+    if (mapped.memory.binding === true) {
+      throw new PatchError(
+        "the patched note still reads as binding",
+        "This is a defect in the patcher, not in your note. Nothing was written."
+      );
+    }
+    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."
+      );
+    }
+    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`,
+        "Taking a marking back 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`,
+        "Taking a marking back leaves what the note says exactly as it was \u2014 and the summary is what recall matches on. Nothing was written."
+      );
+    }
+    if (was.memory.title !== mapped.memory.title) {
+      throw new PatchError(
+        `${proposal.action} changed the title, which it must never do`,
+        "Taking a marking back 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`,
+        "A memory that no longer binds is still current. To take it out of the answers as well, use retire. Nothing was written."
+      );
+    }
+    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)
   );
@@ -5944,11 +6962,13 @@ function reversePatch(content, patch) {
   }
   return null;
 }
-var PATCHABLE_KEYS, NEVER_WRITTEN_KEYS, STATUS_WRITING_ACTIONS, KIND_WRITING_ACTIONS, NAMESPACE2, FENCE_RE, LOOKS_FENCED_RE, PatchError, BLOCK_KEY_RE, ANY_INDENTED_KEY_RE;
+var PATCHABLE_KEYS, NEVER_WRITTEN_KEYS, STATUS_WRITING_ACTIONS, KIND_WRITING_ACTIONS, SCOPE_WRITING_ACTIONS, NAMESPACE2, FENCE_RE, LOOKS_FENCED_RE, PatchError, BLOCK_KEY_RE, ANY_INDENTED_KEY_RE;
 var init_patch = __esm({
   "../../packages/memory-engine/src/proposal/patch.ts"() {
     "use strict";
     init_markdown_mapping();
+    init_rule_budget();
+    init_schema();
     init_schema2();
     PATCHABLE_KEYS = [
       // The conclusion itself.
@@ -5972,6 +6992,7 @@ var init_patch = __esm({
     NEVER_WRITTEN_KEYS = ["id", "type", "scope", "aliases", "status", "kind"];
     STATUS_WRITING_ACTIONS = ["retire", "unretire"];
     KIND_WRITING_ACTIONS = ["reclassify"];
+    SCOPE_WRITING_ACTIONS = ["rescope"];
     NAMESPACE2 = "memgineering";
     FENCE_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(\r?\n|$)/;
     LOOKS_FENCED_RE = /^---[ \t]*\r?\n/;
@@ -6013,15 +7034,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",
@@ -6088,23 +7109,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 = [];
@@ -6114,16 +7148,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;
@@ -6144,16 +7192,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";
@@ -6206,26 +7266,35 @@ var init_rank = __esm({
       binding: 5
     };
     STALE_BASE_DAYS = 30;
+    SURFACED_SHARE = 0.5;
+    DELIBERATE = /* @__PURE__ */ new Set(["open", "publish", "adapt", "read-public"]);
   }
 });
 
 // ../../packages/memory-engine/src/index.ts
 var src_exports2 = {};
 __export(src_exports2, {
+  BASE_TEMPLATES: () => BASE_TEMPLATES,
   CONSOLIDATION_RULES: () => CONSOLIDATION_RULES,
   CaptureCandidateSchema: () => CaptureCandidateSchema,
   ClaimConfidenceSchema: () => ClaimConfidenceSchema,
   ClaimSchema: () => ClaimSchema,
   CommitInputSchema: () => CommitInputSchema,
+  DEFAULT_RULE_BUDGET: () => DEFAULT_RULE_BUDGET,
   DEFAULT_TTL_DAYS: () => DEFAULT_TTL_DAYS,
+  DERIVED_BLUEPRINT: () => DERIVED_BLUEPRINT,
+  DERIVED_DIR: () => DERIVED_DIR,
+  GLOBAL_SCOPE: () => GLOBAL_SCOPE,
   IllegalTransitionError: () => IllegalTransitionError,
   KIND_WRITING_ACTIONS: () => KIND_WRITING_ACTIONS,
+  MEANING_ONLY_NOTE: () => MEANING_ONLY_NOTE,
   MappingModeSchema: () => MappingModeSchema,
   MemoryKindSchema: () => MemoryKindSchema,
   MemorySchema: () => MemorySchema,
   MemoryStatusSchema: () => MemoryStatusSchema,
   NEVER_WRITTEN_KEYS: () => NEVER_WRITTEN_KEYS,
   NO_REASON_GIVEN: () => NO_REASON_GIVEN,
+  OBSERVATIONS_DIR: () => OBSERVATIONS_DIR,
   PATCHABLE_KEYS: () => PATCHABLE_KEYS,
   PatchError: () => PatchError,
   ProposalActionSchema: () => ProposalActionSchema,
@@ -6234,14 +7303,23 @@ __export(src_exports2, {
   ProposedClaimSchema: () => ProposedClaimSchema,
   ProposedRelationsSchema: () => ProposedRelationsSchema,
   ProvenanceSchema: () => ProvenanceSchema,
+  QUERY_EMBEDDING_PREFIX: () => QUERY_EMBEDDING_PREFIX,
   RECALL_DEPTHS: () => RECALL_DEPTHS,
+  RETIRED_BASE_TEMPLATES: () => RETIRED_BASE_TEMPLATES,
+  RULE_BLOCK_BUDGET: () => RULE_BLOCK_BUDGET,
+  RULE_WIDTH_MAX: () => RULE_WIDTH_MAX,
+  RULE_WIDTH_MIN: () => RULE_WIDTH_MIN,
+  RULE_WIRE_WIDTH: () => RULE_WIRE_WIDTH,
   RecallOptionError: () => RecallOptionError,
   RelationSchema: () => RelationSchema,
   RelationSourceSchema: () => RelationSourceSchema,
   RelationTypeSchema: () => RelationTypeSchema,
   SCOPE_LIMIT: () => SCOPE_LIMIT,
+  SCOPE_SPREAD_FIELD: () => SCOPE_SPREAD_FIELD,
+  SCOPE_WRITING_ACTIONS: () => SCOPE_WRITING_ACTIONS,
   SEMANTIC_CANDIDATES: () => SEMANTIC_CANDIDATES,
   SEMANTIC_FIELDS: () => SEMANTIC_FIELDS,
+  SETUP_PROGRESS_CODES: () => SETUP_PROGRESS_CODES,
   STATUS_FOR_ACTION: () => STATUS_FOR_ACTION,
   STATUS_WRITING_ACTIONS: () => STATUS_WRITING_ACTIONS,
   StorableActionSchema: () => StorableActionSchema,
@@ -6249,6 +7327,7 @@ __export(src_exports2, {
   TELEMETRY_MESSAGE_LIMIT: () => TELEMETRY_MESSAGE_LIMIT,
   TelemetryErrorPayloadSchema: () => TelemetryErrorPayloadSchema2,
   TransitionSchema: () => TransitionSchema,
+  UNFILLED_FIELDS: () => UNFILLED_FIELDS,
   accept: () => accept,
   addedLines: () => addedLines,
   applyProposal: () => applyProposal,
@@ -6270,28 +7349,39 @@ __export(src_exports2, {
   commit: () => commit,
   computePatch: () => computePatch,
   confidenceOf: () => confidenceOf,
+  declaredScope: () => declaredScope,
+  declaredScopeOf: () => declaredScopeOf,
   defaultExpiry: () => defaultExpiry,
   defaultStateRoot: () => defaultStateRoot,
   deleteProposal: () => deleteProposal,
   detectConsolidation: () => detectConsolidation,
   expireIfDue: () => expireIfDue,
+  expireInput: () => expireInput,
   findConflicts: () => findConflicts,
   freshnessOf: () => freshnessOf,
+  isBindingAction: () => isBindingAction,
   isClassifyAction: () => isClassifyAction,
+  isExactUntouchedBase: () => isExactUntouchedBase,
   isExpired: () => isExpired2,
+  isGlobalScope: () => isGlobalScope,
   isLifecycleAction: () => isLifecycleAction,
   isRecallDepth: () => isRecallDepth,
+  isScopeAction: () => isScopeAction,
+  isTemplateBody: () => isTemplateBody,
   isTerminal: () => isTerminal,
-  isUntouchedBase: () => isUntouchedBase,
+  isUnwrittenBody: () => isUnwrittenBody,
+  isValidityAction: () => isValidityAction,
   lifecycleInput: () => lifecycleInput,
   listProposals: () => listProposals,
   loadProposal: () => loadProposal,
   mapNoteToMemory: () => mapNoteToMemory,
+  markUnfilled: () => markUnfilled,
   matchBoundaryTerms: () => matchBoundaryTerms,
   missingCounterparts: () => missingCounterparts,
   needsRebase: () => needsRebase,
   newProposalId: () => newProposalId,
   noLifecycleReason: () => noLifecycleReason,
+  ownEntry: () => ownEntry,
   prepare: () => prepare,
   prepareForMemory: () => prepareForMemory,
   previewProposal: () => previewProposal,
@@ -6307,15 +7397,23 @@ __export(src_exports2, {
   reconcile: () => reconcile,
   redact: () => redact,
   renderNewNote: () => renderNewNote,
+  rescopeInput: () => rescopeInput,
   resolveDetail: () => resolveDetail,
   reversePatch: () => reversePatch,
   reviseInput: () => reviseInput,
+  ruleLane: () => ruleLane,
+  rulePassage: () => rulePassage,
+  ruleTextOf: () => ruleTextOf,
+  ruleWidthFor: () => ruleWidthFor,
   saveProposal: () => saveProposal,
   saysNothingNew: () => saysNothingNew,
+  scopeSpread: () => scopeSpread,
   searchMemories: () => searchMemories,
   semanticSourceFromVectors: () => semanticSourceFromVectors,
+  splitRuleBudget: () => splitRuleBudget,
   terms: () => terms,
   transition: () => transition,
+  unbindInput: () => unbindInput,
   validateBoundaryTerm: () => validateBoundaryTerm,
   variantsOf: () => variantsOf,
   verifyPatch: () => verifyPatch,
@@ -6326,6 +7424,9 @@ var init_src3 = __esm({
   "../../packages/memory-engine/src/index.ts"() {
     "use strict";
     init_schema();
+    init_layout();
+    init_rule_budget();
+    init_rule_text();
     init_boundary();
     init_markdown_mapping();
     init_build();
@@ -6333,6 +7434,11 @@ var init_src3 = __esm({
     init_reconcile();
     init_planner();
     init_semantic();
+    init_unfilled();
+    init_setup_progress();
+    init_query_prefix();
+    init_base_templates();
+    init_scope_spread();
     init_conflicts();
     init_search();
     init_schema2();
@@ -6927,13 +8033,18 @@ async function useClient() {
         } catch (err) {
           const code = err.code;
           if (code === "authorization_pending") {
-            if (debug) process.stderr.write("[kordis] auto-finalize: authorization_pending (keeping pending)\n");
+            if (debug)
+              process.stderr.write(
+                "[kordis] auto-finalize: authorization_pending (keeping pending)\n"
+              );
           } else {
             await clearPending();
             if (debug) {
               const msg = err instanceof Error ? err.message : String(err);
-              process.stderr.write(`[kordis] auto-finalize: poll failed (code=${code ?? "none"}): ${msg}
-`);
+              process.stderr.write(
+                `[kordis] auto-finalize: poll failed (code=${code ?? "none"}): ${msg}
+`
+              );
             }
             void reportError("auto_finalize_stage1_fail", err);
           }
@@ -6957,7 +8068,8 @@ async function useClient() {
             cfg = { ...cfg, username, sessionId: pollResult.session_id };
             await saveCliConfig(cfg);
             await clearPending();
-            if (debug) process.stderr.write(`[kordis] auto-finalize: persisted tokens for ${username}
+            if (debug)
+              process.stderr.write(`[kordis] auto-finalize: persisted tokens for ${username}
 `);
           } catch (err) {
             await clearPending();
@@ -6986,31 +8098,51 @@ async function useClient() {
       }
     } : {}
   });
+  const renewTokens = async (user, sent) => {
+    try {
+      const refreshed = await api.refreshSession(sent);
+      currentTokens = {
+        access_token: refreshed.access_token,
+        refresh_token: refreshed.refresh_token,
+        session_id: refreshed.session_id,
+        expires_at_epoch: Math.floor(Date.now() / 1e3) + refreshed.expires_in
+      };
+      await keychain.save(user, currentTokens);
+      await saveCliConfig({ ...cfg, sessionId: refreshed.session_id });
+      return true;
+    } catch (refreshErr) {
+      if (!lostRefreshRace(refreshErr)) return false;
+      const stored = await storedPairOtherThan(user, sent);
+      if (stored === null) return false;
+      currentTokens = stored;
+      return true;
+    }
+  };
   const authedRequest = async (fn) => {
     try {
       return await fn(api);
     } catch (err) {
-      if (err instanceof KordisApiError && err.code === "not_authenticated" && currentTokens && username) {
-        try {
-          const refreshed = await api.refreshSession(currentTokens.refresh_token);
-          currentTokens = {
-            access_token: refreshed.access_token,
-            refresh_token: refreshed.refresh_token,
-            session_id: refreshed.session_id,
-            expires_at_epoch: Math.floor(Date.now() / 1e3) + refreshed.expires_in
-          };
-          await keychain.save(username, currentTokens);
-          await saveCliConfig({ ...cfg, sessionId: refreshed.session_id });
-          return await fn(api);
-        } catch {
-          throw err;
-        }
-      }
-      throw err;
+      const renewed = err instanceof KordisApiError && err.code === "not_authenticated" && currentTokens !== null && username !== null && await renewTokens(username, currentTokens.refresh_token);
+      if (!renewed) throw err;
     }
+    return fn(api);
   };
   return { api, keychain, username, apiUrl: cfg.apiUrl, authedRequest };
 }
+function lostRefreshRace(err) {
+  return err instanceof KordisApiError && err.status === 401 && isRefreshRace({ error: { code: err.code, flags: err.flags } });
+}
+var RACE_REREADS_AT_MS = [500, 1e3, 2e3];
+async function storedPairOtherThan(username, sent) {
+  let waited = 0;
+  for (const at of RACE_REREADS_AT_MS) {
+    await new Promise((resolve6) => setTimeout(resolve6, at - waited));
+    waited = at;
+    const stored = await createKeychain().then((store) => store.load(username)).catch(() => null);
+    if (stored !== null && stored.refresh_token !== sent) return stored;
+  }
+  return null;
+}
 
 // src/ui.ts
 import kleur from "kleur";
@@ -8332,6 +9464,7 @@ function lintForLeaks(sources) {
 }
 
 // src/commands/push.ts
+init_src();
 var collect = (val, acc) => acc.concat(val);
 function toLineage(raws, kind) {
   return (raws ?? []).map((raw) => {
@@ -8346,7 +9479,10 @@ function toLineage(raws, kind) {
 var ASSET_MAX_BYTES = 2 * 1024 * 1024;
 var BUNDLE_MAX_BYTES = 5 * 1024 * 1024;
 function pushCommand() {
-  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option("--slug <slug>", 'override slug; accepts "user/slug" to point at a specific package').option("--type <type>", "override type inference").option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").option(
+  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option("--slug <slug>", 'override slug; accepts "user/slug" to point at a specific package').option(
+    "--type <type>",
+    "type to write into a frontmatter that names none (else a SKILL.md, folder or .skill is a skill); refused if the frontmatter names another"
+  ).option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").option(
     "--adapted-from <slug>",
     "source this package was adapted from (repeatable); records lineage",
     collect,
@@ -8361,17 +9497,15 @@ function pushCommand() {
       let contentLabel = "SKILL.md";
       if (s.isDirectory()) {
         ({ content, assets } = await bundleDirectory(abs));
-        content = ensureTypeField(content, "skill");
+        content = resolveType(content, opts.type, "skill");
       } else if (abs.endsWith(".skill")) {
         ({ content, assets } = await bundleSkillZip(abs));
-        content = ensureTypeField(content, "skill");
+        content = resolveType(content, opts.type, "skill");
       } else {
         content = await readFile6(abs, "utf8");
         contentLabel = basename(abs);
         const isSkillFilename = abs.endsWith("/SKILL.md") || abs.endsWith(".skill.md");
-        if (isSkillFilename) {
-          content = ensureTypeField(content, "skill");
-        }
+        content = resolveType(content, opts.type, isSkillFilename ? "skill" : void 0);
       }
       let nameFromFm = null;
       try {
@@ -8451,7 +9585,6 @@ function pushCommand() {
             bump: opts.bump,
             slug: opts.slug && !opts.slug.includes("/") ? opts.slug : void 0,
             target_full_slug: targetFullSlug,
-            type: opts.type,
             changelog: opts.changelog,
             lineage: lineage.length > 0 ? lineage : void 0,
             dry_run: !!opts.dryRun
@@ -8587,15 +9720,39 @@ function printLeakWarnings(findings) {
     printHuman(c.yellow(`    - ${f.message}`));
   }
 }
-function ensureTypeField(content, defaultType) {
+function resolveType(content, typeFlag, inferred) {
+  if (typeFlag === void 0) return inferred ? ensureTypeField(content, inferred) : content;
+  const declared = frontmatterType(content);
+  if (declared === void 0) return ensureTypeField(content, typeFlag);
+  if (declared !== typeFlag) {
+    throw new KordisApiError(400, {
+      error: {
+        code: "usage_error",
+        message: `--type "${typeFlag}" disagrees with the type in the frontmatter, "${declared}"`,
+        hint: `This file's frontmatter says \`type: ${declared}\`; change it or drop \`--type\`.`
+      }
+    });
+  }
+  return content;
+}
+function frontmatterType(content) {
+  try {
+    const value = parseFrontmatter(content).frontmatter?.["type"];
+    return typeof value === "string" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function ensureTypeField(content, type) {
   const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
   if (!fmMatch) return content;
   const fmBlock = fmMatch[1];
   if (/^type\s*:/m.test(fmBlock)) return content;
-  const injected = fmMatch[0].replace(/^---\r?\n/, `---
-type: ${defaultType}
+  const scalar = HarnessTypeSchema.safeParse(type).success ? type : JSON.stringify(type);
+  const injected = fmMatch[0].replace(/^---\r?\n/, () => `---
+type: ${scalar}
 `);
-  return content.replace(fmMatch[0], injected);
+  return content.replace(fmMatch[0], () => injected);
 }
 var EXCLUDE_NAMES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
 var EXCLUDE_DIRS = /* @__PURE__ */ new Set(["__pycache__", "node_modules", ".git", "evals", "dist", ".turbo"]);
@@ -8609,15 +9766,15 @@ function shouldExclude(relPath, isDir) {
   if (EXCLUDE_EXTS.has(ext)) return true;
   return false;
 }
-async function walkDir(base, relDir, collected) {
-  const entries = await readdir2(join8(base, relDir), { withFileTypes: true });
+async function walkDir(base2, relDir, collected) {
+  const entries = await readdir2(join8(base2, relDir), { withFileTypes: true });
   for (const entry of entries) {
     const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
     if (shouldExclude(rel, entry.isDirectory())) continue;
     if (entry.isDirectory()) {
-      await walkDir(base, rel, collected);
+      await walkDir(base2, rel, collected);
     } else if (entry.isFile()) {
-      collected.push({ rel, abs: join8(base, rel) });
+      collected.push({ rel, abs: join8(base2, rel) });
     }
   }
 }
@@ -9271,45 +10428,31 @@ function getTranslator(type, format) {
   return fn;
 }
 
-// src/lockfile.ts
-init_brand();
-import { join as join9 } from "path";
-import { readFile as readFile7, writeFile as writeFile5, mkdir as mkdir5 } from "fs/promises";
-function kordisHome2() {
-  return brandHome();
-}
-function lockfilePath() {
-  return join9(kordisHome2(), "installed.json");
-}
-function lockfileDisplayPath() {
-  const path2 = lockfilePath();
-  const home = process.env["HOME"];
-  return home && path2.startsWith(home) ? "~" + path2.slice(home.length) : path2;
-}
-async function readLockfile() {
-  try {
-    const raw = await readFile7(lockfilePath(), "utf8");
-    return JSON.parse(raw);
-  } catch {
-    return { packages: {} };
-  }
-}
-async function writeLockfile(lf) {
-  await mkdir5(kordisHome2(), { recursive: true });
-  await writeFile5(lockfilePath(), JSON.stringify(lf, null, 2) + "\n", {
-    encoding: "utf8",
-    mode: 384
-  });
-}
-async function recordInstalled(fullSlug, entry) {
-  const lf = await readLockfile();
-  lf.packages[fullSlug] = entry;
-  await writeLockfile(lf);
-}
-
-// src/lib/merge-emitted-file.ts
+// ../../packages/translators/src/merge-emitted-file.ts
 import tomlLib2 from "@iarna/toml";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+var MergeRefusal = class extends Error {
+  code;
+  reason;
+  constructor(reason) {
+    super(refusalMessage(reason));
+    this.name = "MergeRefusal";
+    this.code = reason.kind === "prototype_key" ? "unsafe_package_config" : "merge_refused";
+    this.reason = reason;
+  }
+};
+function refusalMessage(reason) {
+  switch (reason.kind) {
+    case "prototype_key":
+      return `refusing to merge config fragment \u2014 prototype-polluting key "${reason.key}" at ${reason.path}`;
+    case "malformed_file":
+      return `refusing to merge into "${reason.targetPath}" \u2014 existing file is not valid ${reason.format.toUpperCase()}: ${reason.parseError}`;
+    case "non_object_root":
+      return `refusing to merge into "${reason.targetPath}" \u2014 existing ${reason.format.toUpperCase()} root is not an object`;
+    case "dangling_marker":
+      return `refusing to merge \u2014 found a "kordis:${reason.fullSlug}" start marker with no matching end marker`;
+  }
+}
 function isPlainObject(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -9334,11 +10477,7 @@ function assertNoProtoKeys(value, path2) {
   if (!isPlainObject(value)) return;
   for (const [k, v] of Object.entries(value)) {
     if (PROTO_KEYS.has(k)) {
-      const e = new Error(
-        `refusing to merge config fragment \u2014 prototype-polluting key "${k}" at ${[...path2, k].join(".")}`
-      );
-      e.hint = "The package emits a config key named __proto__/constructor/prototype, which no legitimate tool config needs. Report it to the author if you did not publish it.";
-      throw e;
+      throw new MergeRefusal({ kind: "prototype_key", key: k, path: [...path2, k].join(".") });
     }
     assertNoProtoKeys(v, [...path2, k]);
   }
@@ -9347,19 +10486,15 @@ function isOwnedServerLeaf(path2) {
   return path2.length === 2 && (path2[0] === "mcpServers" || path2[0] === "mcp_servers");
 }
 function deepMergeFragment(existing, fragment, path2 = []) {
-  if (path2.length === 0) assertNoProtoKeys(fragment, []);
+  assertNoProtoKeys(fragment, path2);
+  return mergeAt(existing, fragment, path2);
+}
+function mergeAt(existing, fragment, path2) {
   if (isOwnedServerLeaf(path2)) return fragment;
   if (isPlainObject(existing) && isPlainObject(fragment)) {
     const out = { ...existing };
     for (const [k, v] of Object.entries(fragment)) {
-      if (PROTO_KEYS.has(k)) {
-        const e = new Error(
-          `refusing to merge config fragment \u2014 prototype-polluting key "${k}" at ${[...path2, k].join(".")}`
-        );
-        e.hint = "The package emits a config key named __proto__/constructor/prototype, which no legitimate tool config needs. Report it to the author if you did not publish it.";
-        throw e;
-      }
-      out[k] = deepMergeFragment(existing[k], v, [...path2, k]);
+      out[k] = mergeAt(existing[k], v, [...path2, k]);
     }
     return out;
   }
@@ -9402,18 +10537,15 @@ function mergeStructuredFile(existingRaw, fragmentRaw, format, targetPath) {
   try {
     existing = parseStructured(existingRaw, format);
   } catch (err) {
-    const e = new Error(
-      `refusing to merge into "${targetPath}" \u2014 existing file is not valid ${format.toUpperCase()}: ${err.message}`
-    );
-    e.hint = `Fix or remove the malformed ${targetPath}, then re-run \`kordis pull\`/\`kordis update\`. Refusing to overwrite it blind \u2014 it may hold config from other tools/packages.`;
-    throw e;
+    throw new MergeRefusal({
+      kind: "malformed_file",
+      targetPath,
+      format,
+      parseError: err.message
+    });
   }
   if (!isPlainObject(existing) && isPlainObject(fragment)) {
-    const e = new Error(
-      `refusing to merge into "${targetPath}" \u2014 existing ${format.toUpperCase()} root is not an object`
-    );
-    e.hint = `${targetPath} parses but its top level is not an object, so a config fragment can't be merged in. Move the file aside (or fix its shape), then re-run \`kordis pull\`/\`kordis update\`.`;
-    throw e;
+    throw new MergeRefusal({ kind: "non_object_root", targetPath, format });
   }
   const merged = deepMergeFragment(existing, fragment);
   return stringifyStructured(merged, format);
@@ -9435,15 +10567,67 @@ function mergeFencedFile(existingRaw, fullSlug, block) {
     return existingRaw.slice(0, startMatch.index) + trimmedBlock + existingRaw.slice(spanEnd);
   }
   if (startMatch && endIdx === -1) {
-    const e = new Error(
-      `refusing to merge \u2014 found a "kordis:${fullSlug}" start marker with no matching end marker`
-    );
-    e.hint = `The file has a dangling <!-- kordis:${fullSlug}:...:start --> marker. Delete that line (or restore its <!-- kordis:${fullSlug}:end --> line), then re-run \`kordis pull\`/\`kordis update\`.`;
-    throw e;
+    throw new MergeRefusal({ kind: "dangling_marker", fullSlug });
   }
   return existingRaw.trimEnd() + "\n\n" + trimmedBlock + "\n";
 }
 
+// src/lockfile.ts
+init_brand();
+import { join as join9 } from "path";
+import { readFile as readFile7, writeFile as writeFile5, mkdir as mkdir5 } from "fs/promises";
+function kordisHome2() {
+  return brandHome();
+}
+function lockfilePath() {
+  return join9(kordisHome2(), "installed.json");
+}
+function lockfileDisplayPath() {
+  const path2 = lockfilePath();
+  const home = process.env["HOME"];
+  return home && path2.startsWith(home) ? "~" + path2.slice(home.length) : path2;
+}
+async function readLockfile() {
+  try {
+    const raw = await readFile7(lockfilePath(), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return { packages: {} };
+  }
+}
+async function writeLockfile(lf) {
+  await mkdir5(kordisHome2(), { recursive: true });
+  await writeFile5(lockfilePath(), JSON.stringify(lf, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 384
+  });
+}
+async function recordInstalled(fullSlug, entry) {
+  const lf = await readLockfile();
+  lf.packages[fullSlug] = entry;
+  await writeLockfile(lf);
+}
+
+// src/lib/merge-refusal.ts
+function adaptMergeRefusal(err) {
+  if (!(err instanceof MergeRefusal)) return null;
+  const e = new Error(err.message);
+  e.hint = mergeRefusalHint(err.reason);
+  return e;
+}
+function mergeRefusalHint(reason) {
+  switch (reason.kind) {
+    case "prototype_key":
+      return "The package emits a config key named __proto__/constructor/prototype, which no legitimate tool config needs. Report it to the author if you did not publish it.";
+    case "malformed_file":
+      return `Fix or remove the malformed ${reason.targetPath}, then re-run \`kordis pull\`/\`kordis update\`. Refusing to overwrite it blind \u2014 it may hold config from other tools/packages.`;
+    case "non_object_root":
+      return `${reason.targetPath} parses but its top level is not an object, so a config fragment can't be merged in. Move the file aside (or fix its shape), then re-run \`kordis pull\`/\`kordis update\`.`;
+    case "dangling_marker":
+      return `The file has a dangling <!-- kordis:${reason.fullSlug}:...:start --> marker. Delete that line (or restore its <!-- kordis:${reason.fullSlug}:end --> line), then re-run \`kordis pull\`/\`kordis update\`.`;
+  }
+}
+
 // src/commands/pull.ts
 async function requireExecutableApproval(pkg, fullSlug, files, approve2) {
   if (!pkg.capabilities.executable) return;
@@ -9841,7 +11025,12 @@ async function applyEmittedFile(abs, f, fullSlug, notes) {
     if (err.code !== "ENOENT") throw err;
   }
   if (f.format === "json" || f.format === "yaml" || f.format === "toml") {
-    const merged2 = mergeStructuredFile(existingRaw, f.content, f.format, abs);
+    let merged2;
+    try {
+      merged2 = mergeStructuredFile(existingRaw, f.content, f.format, abs);
+    } catch (err) {
+      throw adaptMergeRefusal(err) ?? err;
+    }
     if (existingRaw !== null && existingRaw.trim() !== "") {
       notes?.push(
         `merged into ${f.path} \u2014 comments/formatting in the existing file are not preserved`
@@ -9850,11 +11039,17 @@ async function applyEmittedFile(abs, f, fullSlug, notes) {
     await writeFile6(abs, merged2, "utf8");
     return;
   }
-  const merged = mergeFencedFile(existingRaw, fullSlug, f.content);
+  let merged;
+  try {
+    merged = mergeFencedFile(existingRaw, fullSlug, f.content);
+  } catch (err) {
+    throw adaptMergeRefusal(err) ?? err;
+  }
   await writeFile6(abs, merged, "utf8");
 }
 
 // src/commands/read.ts
+init_src2();
 init_sections();
 import { Command as Command6 } from "commander";
 
@@ -9874,6 +11069,15 @@ function untrustedFenceNotice(sentinel) {
 }
 
 // src/commands/read.ts
+var shellWord = (word) => /^[\w./@:+-]+$/.test(word) ? word : JSON.stringify(word);
+function readAgainCommand(fullSlug, parsed, opts) {
+  const suffix = parsed.version ? `@${parsed.version}` : parsed.range ? `@${parsed.range}` : "";
+  return [
+    `kordis read ${shellWord(`${fullSlug}${suffix}`)}`,
+    ...opts.pin === void 0 ? [] : [`--pin ${shellWord(opts.pin)}`],
+    ...opts.allowPending ? ["--allow-pending"] : []
+  ].join(" ");
+}
 function readCommand() {
   return new Command6("read").description("fetch a package body into the agent context (no install)").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--pin <semver>", "pin to an exact version (overrides @suffix)").option("--outline", "print only the section map (skeleton) \u2014 cheap on context", false).option("--section <name>", "print only one section (see names with --outline)").action(
     async (rawSlug, opts) => {
@@ -9951,9 +11155,19 @@ Bundled files \u2014 fetch with ${c.cyan(`kordis pull ${res.full_slug}`)}:
         const sec = sectionOf(res.body, opts.section);
         if (!sec) {
           const names = outlineOf(res.body).sections.map((s) => s.name).join(", ");
+          const readAgain = readAgainCommand(res.full_slug, parsed, opts);
+          if (isJsonMode()) {
+            throw new KordisApiError(400, {
+              error: {
+                code: "usage_error",
+                message: `section "${opts.section}" not found`,
+                hint: names ? `Available sections: ${names}. Read one with \`${readAgain} --section <name>\`.` : `This package has no sub-sections \u2014 read the whole body with \`${readAgain}\`.`
+              }
+            });
+          }
           process.stderr.write(
             `${c.red("\u2717")} section "${opts.section}" not found. Available: ${names || "(none \u2014 this package has no sub-sections)"}
-  See the map with ${c.cyan(`kordis read ${res.full_slug} --outline`)}.
+  See the map with ${c.cyan(`${readAgain} --outline`)}.
 `
           );
           process.exitCode = 2;
@@ -10023,6 +11237,7 @@ import { homedir as homedir4 } from "os";
 import { join as join11 } from "path";
 var PER_FILE_CAP = 16 * 1024;
 var TOTAL_CAP = 48 * 1024;
+var TRUNCATION_RESERVE = 64;
 async function pathExists3(p) {
   try {
     await access3(p);
@@ -10033,6 +11248,7 @@ async function pathExists3(p) {
 }
 function capContent(raw, cap) {
   if (Buffer.byteLength(raw, "utf8") <= cap) return { content: raw, truncated: false };
+  const fill = cap - TRUNCATION_RESERVE;
   const lines = raw.split("\n");
   let acc = 0;
   let lastHeadingIdx = -1;
@@ -10041,7 +11257,7 @@ function capContent(raw, cap) {
     const line = lines[i] ?? "";
     const lineBytes = Buffer.byteLength(`${line}
 `, "utf8");
-    if (acc + lineBytes > cap) {
+    if (acc + lineBytes > fill) {
       cutIdx = i;
       break;
     }
@@ -10049,6 +11265,7 @@ function capContent(raw, cap) {
     if (/^#{1,6}\s/.test(line)) lastHeadingIdx = i;
   }
   const cut = lastHeadingIdx > cutIdx / 2 ? lastHeadingIdx : cutIdx;
+  if (cut === 0) return null;
   const kept = lines.slice(0, cut).join("\n");
   return {
     content: `${kept}
@@ -10077,7 +11294,6 @@ async function readHarnessContext(cwd = process.cwd(), home = homedir4()) {
   const files = [];
   let totalBytes = 0;
   for (const cand of candidates) {
-    if (totalBytes >= TOTAL_CAP) break;
     if (!await pathExists3(cand.path)) continue;
     let raw;
     try {
@@ -10086,7 +11302,9 @@ async function readHarnessContext(cwd = process.cwd(), home = homedir4()) {
       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");
     files.push({
       path: cand.display,
@@ -12743,9 +13961,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 };
@@ -12791,15 +14009,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/memory/exclude.ts
@@ -12845,8 +14063,8 @@ async function openVaultOrExplain(path2) {
 // src/commands/memory/link.ts
 init_brand();
 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();
@@ -13110,7 +14328,7 @@ function excludeCommand() {
   return new Command28("exclude").description("stop reading a note entirely \u2014 the note itself is not changed").argument("<path>", "vault-relative path of the note, e.g. decisions/launch-date.md").option("--yes", "skip the confirmation prompt").option("--vault <path>", "which linked vault the note is in").action(async (path2, opts) => {
     const root = await resolveVaultRoot(opts.vault);
     const target = await mustMatchAFile(root, path2);
-    const base = await readIgnoreFileState(root);
+    const base2 = await readIgnoreFileState(root);
     if (!opts.yes && isJsonMode()) {
       throw memoryError(
         "refusing to change what this vault reads without confirmation",
@@ -13134,7 +14352,7 @@ function excludeCommand() {
         return;
       }
     }
-    const result = await addIgnoreEntry(root, target, base);
+    const result = await addIgnoreEntry(root, target, base2);
     if (!result.ok) {
       printDual({
         json: {
@@ -13172,7 +14390,7 @@ function unexcludeCommand() {
   return new Command28("unexclude").description("read a note again after excluding it").argument("<path>", "vault-relative path of the note").option("--yes", "skip the confirmation prompt").option("--vault <path>", "which linked vault the note is in").action(async (path2, opts) => {
     const root = await resolveVaultRoot(opts.vault);
     const target = path2.normalize("NFC");
-    const base = await readIgnoreFileState(root);
+    const base2 = await readIgnoreFileState(root);
     if (!opts.yes && isJsonMode()) {
       throw memoryError(
         "refusing to change what this vault reads without confirmation",
@@ -13195,7 +14413,7 @@ function unexcludeCommand() {
         return;
       }
     }
-    const result = await removeIgnoreEntry(root, target, base);
+    const result = await removeIgnoreEntry(root, target, base2);
     if (!result.ok) {
       printDual({
         json: {