@vortex-os/base 0.5.0 → 0.6.0

package/dist/index.js

@@ -280,7 +280,8 @@ var dist_exports2 = {};
 __export(dist_exports2, {
   CommandNotFoundError: () => CommandNotFoundError,
   CommandRegistry: () => CommandRegistry,
-  runSlash: () => runSlash
+  runSlash: () => runSlash,
+  runSlashArgv: () => runSlashArgv
 });
 
 // ../modules/slash-commands/dist/registry.js
@@ -337,6 +338,24 @@ async function runSlash(input, { registry, context }) {
   };
   return command.handler(ci);
 }
+async function runSlashArgv(name, argv, { registry, context }) {
+  if (name.length === 0) {
+    throw new Error("Empty command name");
+  }
+  const command = registry.get(name);
+  if (!command) {
+    throw new CommandNotFoundError(name);
+  }
+  const args = parseArgs(argv, command.args);
+  const ci = {
+    raw: [name, ...argv].join(" "),
+    args,
+    rest: argv.join(" "),
+    argv,
+    context
+  };
+  return command.handler(ci);
+}
 function parseArgs(tokens, schema) {
   const out = {};
   if (!schema)
@@ -4199,35 +4218,50 @@ __export(dist_exports14, {
   SESSION_END_COMMAND: () => SESSION_END_COMMAND,
   SESSION_START_COMMAND: () => SESSION_START_COMMAND,
   agendaCommand: () => agendaCommand,
+  applyGlobalSetup: () => applyGlobalSetup,
+  argvToSlash: () => argvToSlash,
   buildInstallCommand: () => buildInstallCommand,
   buildOwnershipManifest: () => buildOwnershipManifest,
   buildRegistry: () => buildRegistry,
   catchUpSessions: () => catchUpSessions,
   checkBaseUpdate: () => checkBaseUpdate,
   collectAgenda: () => collectAgenda,
+  collectCarryover: () => collectCarryover,
   collectSessionStartReport: () => collectSessionStartReport,
   compareSemver: () => compareSemver,
   computeCurateFingerprint: () => computeCurateFingerprint,
+  countUncommitted: () => countUncommitted,
   createAmbientRecaller: () => createAmbientRecaller,
   createRitualRegistry: () => createRitualRegistry,
   curateCommand: () => curateCommand,
   decisionCommand: () => decisionCommand,
+  detectInterruptedGitOp: () => detectInterruptedGitOp,
   detectWorklogGaps: () => detectWorklogGaps,
   ensureVortexHooks: () => ensureVortexHooks,
   ensureWorklogEntry: () => ensureWorklogEntry,
   extractNextUp: () => extractNextUp,
   extractOpenTasks: () => extractOpenTasks,
+  globalMemoryPath: () => globalMemoryPath,
+  globalSettingsHasHook: () => globalSettingsHasHook,
+  globalSettingsPath: () => globalSettingsPath,
+  globalStatePath: () => globalStatePath,
+  inspectGlobalSetup: () => inspectGlobalSetup,
   inspectOwnership: () => inspectOwnership,
+  isInstanceRoot: () => isInstanceRoot,
   isNewer: () => isNewer,
   isStableUpdate: () => isStableUpdate,
   logCommand: () => logCommand,
   ownershipManifestPath: () => ownershipManifestPath,
+  parseAdoptArgs: () => parseAdoptArgs,
   parseSettings: () => parseSettings,
   queryNpmLatest: () => queryNpmLatest,
+  readGlobalInstancePointer: () => readGlobalInstancePointer,
   readInstalledBaseVersion: () => readInstalledBaseVersion,
   recallCommand: () => recallCommand,
+  recordGlobalSetupDecline: () => recordGlobalSetupDecline,
   reindexCommand: () => reindexCommand,
   renderAgenda: () => renderAgenda,
+  renderGlobalBlock: () => renderGlobalBlock,
   renderSessionStartReport: () => renderSessionStartReport,
   repairOwnershipManifest: () => repairOwnershipManifest,
   resolveRepoRoot: () => resolveRepoRoot,
@@ -4240,6 +4274,7 @@ __export(dist_exports14, {
   serializeSettings: () => serializeSettings,
   sessionStartCommand: () => sessionStartCommand,
   templateDestRelPath: () => templateDestRelPath,
+  upsertGlobalBlock: () => upsertGlobalBlock,
   validateCuratePayload: () => validateCuratePayload,
   vortexCommand: () => vortexCommand,
   writeOwnershipManifest: () => writeOwnershipManifest
@@ -4737,14 +4772,18 @@ function todayIso2() {
 
 // ../plugins/session-rituals/dist/commands/vortex.js
 import { spawn } from "child_process";
-import { constants, existsSync as existsSync10 } from "fs";
-import { copyFile as copyFile2, mkdir as mkdir7, readdir as readdir15, readFile as readFile19, stat as stat7, writeFile as writeFile10 } from "fs/promises";
-import { basename as basename7, dirname as dirname5, extname as extname11, join as join24, relative as relative5 } from "path";
+import { constants, existsSync as existsSync11 } from "fs";
+import { copyFile as copyFile2, mkdir as mkdir8, readdir as readdir15, readFile as readFile20, stat as stat7, writeFile as writeFile11 } from "fs/promises";
+import { basename as basename7, dirname as dirname5, extname as extname11, join as join25, relative as relative5 } from "path";
 import { fileURLToPath } from "url";
 
 // ../plugins/session-rituals/dist/ensure-hooks.js
-var SESSION_START_COMMAND = "npx --no-install -p @vortex-os/base vortex session-start";
-var SESSION_END_COMMAND = "npx --no-install -p @vortex-os/base vortex session-end";
+var SESSION_START_COMMAND = "npx --no-install -p @vortex-os/base vortex session-start || exit 0";
+var SESSION_END_COMMAND = "npx --no-install -p @vortex-os/base vortex session-end || exit 0";
+var LEGACY_COMMANDS = {
+  SessionStart: "npx --no-install -p @vortex-os/base vortex session-start",
+  SessionEnd: "npx --no-install -p @vortex-os/base vortex session-end"
+};
 function parseSettings(text) {
   const trimmed = (text ?? "").trim();
   if (trimmed.length === 0)
@@ -4760,22 +4799,46 @@ function parseSettings(text) {
   }
   return parsed;
 }
-function hasCommand(groups, command) {
-  if (!groups)
-    return false;
-  return groups.some((g) => g.hooks?.some((h) => h.command === command));
-}
 function ensureVortexHooks(existing) {
   const base = existing && typeof existing === "object" ? existing : {};
   const hooks = { ...base.hooks ?? {} };
   const added = [];
   const wire = (event, command) => {
-    const groups = hooks[event] ? [...hooks[event]] : [];
-    if (hasCommand(groups, command))
-      return;
-    groups.push({ hooks: [{ type: "command", command }] });
+    const legacy = LEGACY_COMMANDS[event];
+    const src = hooks[event] ?? [];
+    let changed = false;
+    let kept = false;
+    const groups = [];
+    for (const g of src) {
+      const hookList = [];
+      for (const h of g.hooks ?? []) {
+        const migrated = h.command === legacy;
+        const cmd = migrated ? command : h.command;
+        if (cmd === command) {
+          if (kept) {
+            changed = true;
+            continue;
+          }
+          kept = true;
+          if (migrated)
+            changed = true;
+          hookList.push(migrated ? { ...h, command } : h);
+        } else {
+          hookList.push(h);
+        }
+      }
+      if (hookList.length > 0)
+        groups.push({ ...g, hooks: hookList });
+      else
+        changed = true;
+    }
+    if (!kept) {
+      groups.push({ hooks: [{ type: "command", command }] });
+      changed = true;
+    }
     hooks[event] = groups;
-    added.push(event);
+    if (changed)
+      added.push(event);
   };
   wire("SessionStart", SESSION_START_COMMAND);
   wire("SessionEnd", SESSION_END_COMMAND);
@@ -4786,15 +4849,160 @@ function serializeSettings(settings) {
   return JSON.stringify(settings, null, 2) + "\n";
 }
 
+// ../plugins/session-rituals/dist/global-setup.js
+import { homedir } from "os";
+import { existsSync as existsSync9, readFileSync as readFileSync2 } from "fs";
+import { mkdir as mkdir6, readFile as readFile18, writeFile as writeFile10 } from "fs/promises";
+import { isAbsolute as isAbsolute3, join as join23 } from "path";
+async function readFileIfExists(path) {
+  try {
+    return await readFile18(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT")
+      return null;
+    throw e;
+  }
+}
+function isSafeInstanceRoot(dir) {
+  return typeof dir === "string" && dir.trim().length > 0 && isAbsolute3(dir) && !/[\r\n`]/.test(dir) && isInstanceRoot(dir);
+}
+function globalClaudeDir(home = homedir()) {
+  return join23(home, ".claude");
+}
+function globalSettingsPath(home = homedir()) {
+  return join23(globalClaudeDir(home), "settings.json");
+}
+function globalStatePath(home = homedir()) {
+  return join23(globalClaudeDir(home), "vortex-global.json");
+}
+function globalMemoryPath(home = homedir()) {
+  return join23(globalClaudeDir(home), "CLAUDE.md");
+}
+function readGlobalStateRaw(home = homedir()) {
+  try {
+    const parsed = JSON.parse(readFileSync2(globalStatePath(home), "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+function readGlobalInstancePointer(home = homedir()) {
+  const root = readGlobalStateRaw(home)?.instanceRoot;
+  return typeof root === "string" && root.trim().length > 0 ? root.trim() : null;
+}
+function isInstanceRoot(dir) {
+  return existsSync9(join23(dir, ".agent", "vortex.json")) || existsSync9(join23(dir, "data", "_memory", "user_profile.md"));
+}
+function globalSettingsHasHook(home = homedir()) {
+  try {
+    const settings = parseSettings(readFileSync2(globalSettingsPath(home), "utf8"));
+    const wired = (event, command) => Boolean(settings.hooks?.[event]?.some((g) => g.hooks?.some((h) => h.command === command)));
+    return wired("SessionStart", SESSION_START_COMMAND) && wired("SessionEnd", SESSION_END_COMMAND);
+  } catch {
+    return false;
+  }
+}
+function inspectGlobalSetup(home = homedir(), instanceRoot) {
+  const state = readGlobalStateRaw(home) ?? {};
+  const ptr = typeof state.instanceRoot === "string" && state.instanceRoot.trim().length > 0 ? state.instanceRoot.trim() : null;
+  const hooked = globalSettingsHasHook(home);
+  const done = Boolean(ptr) && hooked && (!instanceRoot || ptr === instanceRoot);
+  return { done, declined: typeof state.declinedAt === "string" };
+}
+var BLOCK_BEGIN = "<!-- VORTEX-GLOBAL:BEGIN \u2014 managed by `vortex global-setup`; edit OUTSIDE these markers (this block is regenerated) -->";
+var BLOCK_END = "<!-- VORTEX-GLOBAL:END -->";
+var BLOCK_RE = /^<!-- VORTEX-GLOBAL:BEGIN\b[^\r\n]*-->[ \t]*\r?\n[\s\S]*?\r?\n<!-- VORTEX-GLOBAL:END -->[ \t]*\r?$/m;
+function renderGlobalBlock(instanceRoot) {
+  return [
+    BLOCK_BEGIN,
+    "## VortEX (always-on)",
+    "",
+    `A VortEX instance lives at: \`${instanceRoot}\``,
+    "",
+    "When doing VortEX work (worklog, decisions, recall, memory) \u2014 or any substantive coding you want VortEX's working rules for \u2014 read that instance's `AI-RULES.md` and follow it. Run `vortex` commands so they record to that instance (they resolve it automatically; or pass `VORTEX_REPO_ROOT=<instance path>`). Stay in the current folder \u2014 do not `cd` into the instance.",
+    BLOCK_END
+  ].join("\n");
+}
+function upsertGlobalBlock(existing, instanceRoot) {
+  const block = renderGlobalBlock(instanceRoot);
+  if (BLOCK_RE.test(existing)) {
+    return existing.replace(BLOCK_RE, block);
+  }
+  const head = existing.replace(/\s*$/, "");
+  return (head.length > 0 ? head + "\n\n" : "") + block + "\n";
+}
+async function applyGlobalSetup(opts) {
+  const home = opts.home ?? homedir();
+  const instanceRoot = opts.instanceRoot;
+  const created = [];
+  const modified = [];
+  const skipped = [];
+  const statePath = globalStatePath(home);
+  const settingsPath = globalSettingsPath(home);
+  const instSettingsPath = join23(instanceRoot, ".claude", "settings.json");
+  const mdPath = globalMemoryPath(home);
+  const hadState = existsSync9(statePath);
+  const prevState = readGlobalStateRaw(home) ?? {};
+  const settingsText = await readFileIfExists(settingsPath);
+  const mergedGlobal = ensureVortexHooks(parseSettings(settingsText));
+  const instText = await readFileIfExists(instSettingsPath);
+  const mergedInst = instText !== null ? ensureVortexHooks(parseSettings(instText)) : null;
+  const mdRead = await readFileIfExists(mdPath);
+  const mdText = mdRead ?? "";
+  const nextMd = upsertGlobalBlock(mdText, instanceRoot);
+  await mkdir6(globalClaudeDir(home), { recursive: true });
+  const { declinedAt: _wasDeclined, ...restState } = prevState;
+  const nextState = { ...restState, instanceRoot };
+  if (!hadState || prevState.instanceRoot !== instanceRoot || typeof prevState.declinedAt === "string") {
+    await writeFile10(statePath, JSON.stringify(nextState, null, 2) + "\n", "utf8");
+    (hadState ? modified : created).push(statePath);
+  } else {
+    skipped.push(statePath);
+  }
+  if (!mergedGlobal.alreadyWired) {
+    await writeFile10(settingsPath, serializeSettings(mergedGlobal.settings), "utf8");
+    (settingsText === null ? created : modified).push(settingsPath);
+  } else {
+    skipped.push(settingsPath);
+  }
+  if (mergedInst !== null) {
+    if (!mergedInst.alreadyWired) {
+      await writeFile10(instSettingsPath, serializeSettings(mergedInst.settings), "utf8");
+      modified.push(instSettingsPath);
+    } else {
+      skipped.push(instSettingsPath);
+    }
+  }
+  if (nextMd !== mdText) {
+    await writeFile10(mdPath, nextMd, "utf8");
+    (mdRead === null ? created : modified).push(mdPath);
+  } else {
+    skipped.push(mdPath);
+  }
+  return { created, modified, skipped };
+}
+async function recordGlobalSetupDecline(opts) {
+  const home = opts?.home ?? homedir();
+  const now = opts?.now ?? /* @__PURE__ */ new Date();
+  await mkdir6(globalClaudeDir(home), { recursive: true });
+  const statePath = globalStatePath(home);
+  const prevState = readGlobalStateRaw(home) ?? {};
+  const nextState = { ...prevState, declinedAt: now.toISOString() };
+  await writeFile10(statePath, JSON.stringify(nextState, null, 2) + "\n", "utf8");
+  return statePath;
+}
+
 // ../plugins/session-rituals/dist/update.js
 import { createHash as createHash2 } from "crypto";
-import { existsSync as existsSync9 } from "fs";
-import { copyFile, mkdir as mkdir6, readFile as readFile18 } from "fs/promises";
-import { dirname as dirname4, isAbsolute as isAbsolute3, join as join23, relative as relative4, sep as sep4 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { copyFile, mkdir as mkdir7, readFile as readFile19 } from "fs/promises";
+import { dirname as dirname4, isAbsolute as isAbsolute4, join as join24, relative as relative4, sep as sep4 } from "path";
 var OWNERSHIP_SCHEMA = "vortex-ownership/1";
 var MANIFEST_NAME = "manifest.json";
 function ownershipManifestPath(ctx) {
-  return join23(ctx.dataDir, ".vortex", "ownership.json");
+  return join24(ctx.dataDir, ".vortex", "ownership.json");
 }
 function toPosix(p) {
   return p.split(sep4).join("/");
@@ -4803,7 +5011,7 @@ function sha256(buf) {
   return createHash2("sha256").update(buf).digest("hex");
 }
 async function sha256File(absPath) {
-  return sha256(await readFile18(absPath));
+  return sha256(await readFile19(absPath));
 }
 function templateDestRelPath(templateRelPath) {
   const parts = templateRelPath.split("/");
@@ -4814,9 +5022,9 @@ function templateDestRelPath(templateRelPath) {
   if (top === "routers")
     return tail;
   if (top === "commands")
-    return join23(".claude", "commands", tail);
+    return join24(".claude", "commands", tail);
   if (top === "config")
-    return join23(".agent", tail);
+    return join24(".agent", tail);
   return null;
 }
 function assertUnderRoot(rootAbs, candidateAbs) {
@@ -4825,16 +5033,16 @@ function assertUnderRoot(rootAbs, candidateAbs) {
   const winsensitive = sep4 === "\\";
   const cmp = winsensitive ? rel.toLowerCase() : rel;
   const upCmp = winsensitive ? up.toLowerCase() : up;
-  if (rel === ".." || cmp.startsWith(upCmp) || isAbsolute3(rel)) {
+  if (rel === ".." || cmp.startsWith(upCmp) || isAbsolute4(rel)) {
     throw new Error(`Refusing to write outside the instance root: ${candidateAbs}`);
   }
 }
 async function readTemplateIndex(templatesDir) {
-  const indexPath = join23(templatesDir, MANIFEST_NAME);
-  if (!existsSync9(indexPath))
+  const indexPath = join24(templatesDir, MANIFEST_NAME);
+  if (!existsSync10(indexPath))
     return null;
   try {
-    const parsed = JSON.parse(await readFile18(indexPath, "utf8"));
+    const parsed = JSON.parse(await readFile19(indexPath, "utf8"));
     if (!parsed || !Array.isArray(parsed.files))
       return null;
     return parsed;
@@ -4855,14 +5063,14 @@ async function buildOwnershipManifest(ctx, templatesDir) {
     if (seenDest.has(destRel))
       continue;
     seenDest.add(destRel);
-    const shippedAbs = join23(templatesDir, entry.path);
-    if (!existsSync9(shippedAbs))
+    const shippedAbs = join24(templatesDir, entry.path);
+    if (!existsSync10(shippedAbs))
       continue;
     const sourceSha256 = await sha256File(shippedAbs);
-    const destAbs = join23(ctx.repoRoot, destRel);
+    const destAbs = join24(ctx.repoRoot, destRel);
     assertUnderRoot(ctx.repoRoot, destAbs);
     let installedSha256 = null;
-    if (existsSync9(destAbs)) {
+    if (existsSync10(destAbs)) {
       const onDisk = await sha256File(destAbs);
       installedSha256 = onDisk === sourceSha256 ? sourceSha256 : null;
     }
@@ -4883,14 +5091,14 @@ async function writeOwnershipManifest(ctx, templatesDir) {
   if (!manifest)
     return null;
   const mp = ownershipManifestPath(ctx);
-  await mkdir6(join23(ctx.dataDir, ".vortex"), { recursive: true });
+  await mkdir7(join24(ctx.dataDir, ".vortex"), { recursive: true });
   await atomicWriteFile(mp, JSON.stringify(manifest, null, 2) + "\n");
   return { path: mp, fileCount: manifest.files.length };
 }
 async function inspectOwnership(ctx) {
   const own = await readOwnershipManifest(ctx);
   if (!own) {
-    const malformed = existsSync9(ownershipManifestPath(ctx));
+    const malformed = existsSync10(ownershipManifestPath(ctx));
     return { present: false, malformed, total: 0, pristine: 0, modified: 0, missing: 0, unmanaged: 0 };
   }
   let pristine = 0;
@@ -4902,8 +5110,8 @@ async function inspectOwnership(ctx) {
       unmanaged++;
       continue;
     }
-    const abs = join23(ctx.repoRoot, e.path);
-    if (!existsSync9(abs)) {
+    const abs = join24(ctx.repoRoot, e.path);
+    if (!existsSync10(abs)) {
       missing++;
       continue;
     }
@@ -4920,7 +5128,7 @@ async function inspectOwnership(ctx) {
 }
 async function repairOwnershipManifest(ctx, templatesDir) {
   const mp = ownershipManifestPath(ctx);
-  if (existsSync9(mp)) {
+  if (existsSync10(mp)) {
     const existing = await readOwnershipManifest(ctx);
     return existing ? { status: "already-present", path: mp, fileCount: existing.files.length } : { status: "unreadable", path: mp };
   }
@@ -4929,10 +5137,10 @@ async function repairOwnershipManifest(ctx, templatesDir) {
 }
 async function readOwnershipManifest(ctx) {
   const mp = ownershipManifestPath(ctx);
-  if (!existsSync9(mp))
+  if (!existsSync10(mp))
     return null;
   try {
-    const parsed = JSON.parse(await readFile18(mp, "utf8"));
+    const parsed = JSON.parse(await readFile19(mp, "utf8"));
     if (!parsed || !Array.isArray(parsed.files))
       return null;
     for (const e of parsed.files) {
@@ -4947,6 +5155,7 @@ async function readOwnershipManifest(ctx) {
 }
 async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
   const dryRun = options.dryRun ?? false;
+  const adopt = options.adopt ?? /* @__PURE__ */ new Set();
   const base = {
     subcommand: "update",
     mode: "templates-only",
@@ -4983,6 +5192,8 @@ async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
   const ownByTemplateId = new Map(own.files.map((e) => [e.templateId, e]));
   const seenTemplateIds = /* @__PURE__ */ new Set();
   const seenDest = /* @__PURE__ */ new Set();
+  const adoptMatched = /* @__PURE__ */ new Set();
+  const adoptRefusedConfig = [];
   const ops = [];
   for (const idx of index.files) {
     const destRel = templateDestRelPath(idx.path);
@@ -4992,17 +5203,37 @@ async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
       continue;
     seenDest.add(destRel);
     seenTemplateIds.add(idx.templateId);
-    const shippedAbs = join23(templatesDir, idx.path);
-    if (!existsSync9(shippedAbs))
+    const shippedAbs = join24(templatesDir, idx.path);
+    if (!existsSync10(shippedAbs))
       continue;
     const newSource = await sha256File(shippedAbs);
-    const destAbs = join23(ctx.repoRoot, destRel);
+    const destAbs = join24(ctx.repoRoot, destRel);
     assertUnderRoot(ctx.repoRoot, destAbs);
     const path = toPosix(destRel);
     const templateId = idx.templateId;
-    const exists = existsSync9(destAbs);
+    const exists = existsSync10(destAbs);
     const curHash = exists ? await sha256File(destAbs) : null;
     const prior = ownByTemplateId.get(templateId);
+    if (adopt.has(path)) {
+      adoptMatched.add(path);
+      if (!idx.path.startsWith("config/")) {
+        if (exists && curHash === newSource) {
+          ops.push({
+            action: { path, templateId, action: "unchanged", detail: "already matches the template \u2014 re-tracked" },
+            entry: { templateId, path, sourceSha256: newSource, installedSha256: newSource }
+          });
+        } else {
+          ops.push({
+            action: { path, templateId, action: "adopt", detail: "re-adopted to the template \u2014 your version is backed up" },
+            shippedAbs,
+            destAbs,
+            entry: { templateId, path, sourceSha256: newSource, installedSha256: newSource }
+          });
+        }
+        continue;
+      }
+      adoptRefusedConfig.push(path);
+    }
     if (!prior) {
       if (!exists) {
         ops.push({
@@ -5033,6 +5264,13 @@ async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
       continue;
     }
     if (prior.installedSha256 === null) {
+      if (exists && curHash === newSource) {
+        ops.push({
+          action: { path, templateId, action: "unchanged", detail: "matches the template \u2014 re-tracked" },
+          entry: { templateId, path, sourceSha256: newSource, installedSha256: newSource }
+        });
+        continue;
+      }
       ops.push({
         action: { path, templateId, action: "unmanaged", detail: "on-disk file diverges from the template \u2014 left untouched" },
         entry: { ...prior, sourceSha256: newSource }
@@ -5096,15 +5334,15 @@ async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
   const allOps = [...ops, ...orphanOps];
   const appliedActions = [];
   const finalEntries = [];
-  const backupRoot = join23(ctx.dataDir, ".vortex", "backups", (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-"));
+  const backupRoot = join24(ctx.dataDir, ".vortex", "backups", (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-"));
   let applyError = false;
   const writeDotNew = async (destAbs, content) => {
     const newPath = destAbs + ".new";
-    if (existsSync9(newPath)) {
-      if (await readFile18(newPath, "utf8") === content)
+    if (existsSync10(newPath)) {
+      if (await readFile19(newPath, "utf8") === content)
         return void 0;
-      const backupAbs = join23(backupRoot, toPosix(relative4(ctx.repoRoot, newPath)));
-      await mkdir6(dirname4(backupAbs), { recursive: true });
+      const backupAbs = join24(backupRoot, toPosix(relative4(ctx.repoRoot, newPath)));
+      await mkdir7(dirname4(backupAbs), { recursive: true });
       await copyFile(newPath, backupAbs);
       await atomicWriteFile(newPath, content);
       return toPosix(relative4(ctx.repoRoot, backupAbs));
@@ -5118,16 +5356,16 @@ async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
     if (!dryRun && op.shippedAbs && op.destAbs) {
       const destAbs = op.destAbs;
       try {
-        const content = await readFile18(op.shippedAbs, "utf8");
+        const content = await readFile19(op.shippedAbs, "utf8");
         const newSource = op.entry ? op.entry.sourceSha256 : sha256(content);
         if (action.action === "replace") {
           const prior = ownByTemplateId.get(action.templateId);
-          if (!existsSync9(destAbs)) {
-            await mkdir6(dirname4(destAbs), { recursive: true });
+          if (!existsSync10(destAbs)) {
+            await mkdir7(dirname4(destAbs), { recursive: true });
             await atomicWriteFile(destAbs, content);
           } else if (await sha256File(destAbs) === (prior?.installedSha256 ?? null)) {
-            const backupAbs = join23(backupRoot, action.path);
-            await mkdir6(dirname4(backupAbs), { recursive: true });
+            const backupAbs = join24(backupRoot, action.path);
+            await mkdir7(dirname4(backupAbs), { recursive: true });
             await copyFile(destAbs, backupAbs);
             await atomicWriteFile(destAbs, content);
             action = { ...action, backupPath: toPosix(relative4(ctx.repoRoot, backupAbs)) };
@@ -5144,7 +5382,7 @@ async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
             entry = { templateId: action.templateId, path: action.path, sourceSha256: newSource, installedSha256: prior?.installedSha256 ?? null };
           }
         } else if (action.action === "restore" || action.action === "install") {
-          if (existsSync9(destAbs) && await sha256File(destAbs) !== newSource) {
+          if (existsSync10(destAbs) && await sha256File(destAbs) !== newSource) {
             const backupPath = await writeDotNew(destAbs, content);
             action = {
               path: action.path,
@@ -5156,14 +5394,23 @@ async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
             };
             entry = { templateId: action.templateId, path: action.path, sourceSha256: newSource, installedSha256: null };
           } else {
-            await mkdir6(dirname4(destAbs), { recursive: true });
+            await mkdir7(dirname4(destAbs), { recursive: true });
             await atomicWriteFile(destAbs, content);
           }
         } else if (action.action === "conflict") {
-          await mkdir6(dirname4(destAbs), { recursive: true });
+          await mkdir7(dirname4(destAbs), { recursive: true });
           const backupPath = await writeDotNew(destAbs, content);
           if (backupPath)
             action = { ...action, backupPath };
+        } else if (action.action === "adopt") {
+          if (existsSync10(destAbs)) {
+            const backupAbs = join24(backupRoot, action.path);
+            await mkdir7(dirname4(backupAbs), { recursive: true });
+            await copyFile(destAbs, backupAbs);
+            action = { ...action, backupPath: toPosix(relative4(ctx.repoRoot, backupAbs)) };
+          }
+          await mkdir7(dirname4(destAbs), { recursive: true });
+          await atomicWriteFile(destAbs, content);
         }
       } catch (e) {
         applyError = true;
@@ -5189,11 +5436,11 @@ async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
       generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
       files: newEntries
     };
-    await mkdir6(join23(ctx.dataDir, ".vortex"), { recursive: true });
+    await mkdir7(join24(ctx.dataDir, ".vortex"), { recursive: true });
     await atomicWriteFile(ownershipManifestPath(ctx), JSON.stringify(manifest, null, 2) + "\n");
   }
   const summary = summarize(appliedActions);
-  const changes = summary.replaced + summary.restored + summary.installed;
+  const changes = summary.replaced + summary.restored + summary.installed + summary.adopted;
   const status = dryRun ? "dry-run" : summary.conflicts > 0 ? "conflicts" : changes > 0 ? "updated" : "ok";
   return {
     ...base,
@@ -5202,11 +5449,14 @@ async function runTemplatesUpdate(ctx, templatesDir, options = {}) {
     toVersion,
     actions: appliedActions,
     summary,
-    nextActions: buildNextActions(status, summary, appliedActions, dryRun, fromVersion, toVersion)
+    nextActions: buildNextActions(status, summary, appliedActions, dryRun, fromVersion, toVersion, {
+      adoptRefusedConfig,
+      adoptUnknown: [...adopt].filter((p) => !adoptMatched.has(p))
+    })
   };
 }
 function emptySummary() {
-  return { replaced: 0, restored: 0, installed: 0, conflicts: 0, unchanged: 0, unmanaged: 0, locallyModified: 0, removedUpstream: 0, errors: 0 };
+  return { replaced: 0, restored: 0, installed: 0, conflicts: 0, unchanged: 0, unmanaged: 0, adopted: 0, locallyModified: 0, removedUpstream: 0, errors: 0 };
 }
 function summarize(actions) {
   const s = {
@@ -5216,6 +5466,7 @@ function summarize(actions) {
     conflicts: 0,
     unchanged: 0,
     unmanaged: 0,
+    adopted: 0,
     locallyModified: 0,
     removedUpstream: 0,
     errors: 0
@@ -5237,6 +5488,8 @@ function summarize(actions) {
       s.unchanged++;
     else if (a.action === "unmanaged")
       s.unmanaged++;
+    else if (a.action === "adopt")
+      s.adopted++;
     else if (a.action === "locally-modified")
       s.locallyModified++;
     else if (a.action === "removed-upstream")
@@ -5244,15 +5497,18 @@ function summarize(actions) {
   }
   return s;
 }
-function buildNextActions(status, summary, actions, dryRun, fromVersion, toVersion) {
+function buildNextActions(status, summary, actions, dryRun, fromVersion, toVersion, adopt = {
+  adoptRefusedConfig: [],
+  adoptUnknown: []
+}) {
   const out = [];
   if (dryRun) {
-    const changes = summary.replaced + summary.restored + summary.installed;
+    const changes = summary.replaced + summary.restored + summary.installed + summary.adopted;
     out.push(changes + summary.conflicts === 0 ? `Dry run: templates already current (base ${toVersion}). Nothing would change.` : `Dry run (base ${fromVersion} \u2192 ${toVersion}): would update ${changes}, conflict ${summary.conflicts}. Re-run without --dry-run to apply.`);
   } else if (status === "ok") {
     out.push(`Templates already current (base ${toVersion}). Nothing to do.`);
   } else if (status === "updated") {
-    const n = summary.replaced + summary.restored + summary.installed;
+    const n = summary.replaced + summary.restored + summary.installed + summary.adopted;
     out.push(summary.errors > 0 ? `Refreshed ${n} framework file(s); ${summary.errors} could not be applied \u2014 base stays ${fromVersion} until those resolve. Backups under data/.vortex/backups/.` : `Refreshed ${n} framework file(s) to base ${toVersion}. Backups under data/.vortex/backups/.`);
   } else if (status === "conflicts") {
     out.push(`Updated what was safe; ${summary.conflicts} file(s) you edited were left untouched \u2014 the new template is alongside as \`<file>.new\`.`);
@@ -5261,11 +5517,29 @@ function buildNextActions(status, summary, actions, dryRun, fromVersion, toVersi
         out.push(`  conflict: ${a.path} \u2014 review ${a.newFilePath} and merge by hand.`);
     }
   }
+  if (summary.adopted > 0) {
+    out.push(dryRun ? `Would re-adopt ${summary.adopted} file(s) to the template (your versions would be backed up). Re-run without --dry-run to apply.` : `Re-adopted ${summary.adopted} file(s) to the template \u2014 your prior versions are backed up under data/.vortex/backups/.`);
+  }
   if (summary.errors > 0) {
     out.push(`\u26A0\uFE0F ${summary.errors} file(s) could not be applied (left unchanged) \u2014 see the per-file \`error\`. Re-run after resolving; your files are intact.`);
   }
-  if (summary.unmanaged > 0)
-    out.push(`${summary.unmanaged} file(s) diverge from the template and are not VortEX-managed \u2014 skipped.`);
+  const unmanaged = actions.filter((a) => a.action === "unmanaged");
+  const adoptable = unmanaged.filter((a) => !a.path.startsWith(".agent/"));
+  const userOwned = unmanaged.filter((a) => a.path.startsWith(".agent/"));
+  if (adoptable.length > 0) {
+    out.push(`${adoptable.length} framework file(s) diverge from the template and are NOT getting updates \u2014 run \`vortex update --adopt <path>\` to refresh one to the template (your version is backed up first):`);
+    for (const a of adoptable)
+      out.push(`  diverged: ${a.path}`);
+  }
+  if (userOwned.length > 0) {
+    out.push(`${userOwned.length} user-owned file(s) (your settings) are intentionally not updated \u2014 new options fall back to defaults.`);
+  }
+  for (const p of adopt.adoptRefusedConfig) {
+    out.push(`--adopt ${p}: refused \u2014 that is your settings file; adopting would wipe your settings, and new options already fall back to defaults.`);
+  }
+  for (const p of adopt.adoptUnknown) {
+    out.push(`--adopt ${p}: not a framework-managed file \u2014 nothing to adopt.`);
+  }
   if (summary.locallyModified > 0)
     out.push(`${summary.locallyModified} file(s) you edited are unchanged upstream \u2014 kept as-is.`);
   return out;
@@ -5284,7 +5558,7 @@ var vortexCommand = {
     }
   ],
   handler: async (input) => {
-    const tokens = tokenize(input.rest);
+    const tokens = input.argv ?? tokenize(input.rest);
     const sub = tokens[0] ?? "help";
     const restAfterSub = tokens.slice(1);
     if (sub === "init")
@@ -5299,6 +5573,8 @@ var vortexCommand = {
       return runUpdate(input, restAfterSub);
     if (sub === "sync")
       return runSync(input, restAfterSub);
+    if (sub === "global-setup")
+      return runGlobalSetup(input, restAfterSub);
     if (sub === "help" || sub === "")
       return runHelp();
     if (PLANNED_SUBS.includes(sub)) {
@@ -5342,7 +5618,7 @@ function runHelp() {
       },
       {
         name: "update",
-        description: "Refresh framework-owned templates (routers, slash-command prompts, config) from the installed package \u2014 hash-guarded so files you edited are never overwritten (a `<file>.new` is written instead). Pass --dry-run to preview. Local; no network.",
+        description: "Refresh framework-owned templates (routers, slash-command prompts, config) from the installed package \u2014 hash-guarded so files you edited are never overwritten (a `<file>.new` is written instead). Pass --dry-run to preview. Pass --adopt <path> (repeatable) to force a file you edited back to the template and re-track it (your version is backed up; config is refused). Local; no network.",
         state: "active"
       },
       {
@@ -5350,6 +5626,11 @@ function runHelp() {
         description: "Framework-developer workflow: git pull \u2192 npm install \u2192 npm run build \u2192 npm run verify. Stops on first failure. End users on npm registry do not need this.",
         state: "active"
       },
+      {
+        name: "global-setup",
+        description: "Enable VortEX from ANY folder: merge a SessionStart/SessionEnd hook + instance pointer into your global ~/.claude (settings.json + vortex-global.json) and add a pointer block to ~/.claude/CLAUDE.md. Merge-safe and idempotent. Pass --decline to dismiss the offer so it stops appearing.",
+        state: "active"
+      },
       { name: "help", description: "Show this list.", state: "active" }
     ],
     siblingCommands: [
@@ -5372,18 +5653,19 @@ function runHelp() {
     ]
   };
 }
+var DEFAULT_INIT_TASK = "Setting up my VortEX instance";
 function resolveTemplatesDir() {
   const here = dirname5(fileURLToPath(import.meta.url));
   const candidates = [
-    join24(here, "..", "..", "templates"),
+    join25(here, "..", "..", "templates"),
     // session-rituals: dist/commands -> templates
-    join24(here, "..", "templates"),
+    join25(here, "..", "templates"),
     // base aggregate: dist -> templates
-    join24(here, "templates")
+    join25(here, "templates")
     // defensive: alongside the bundle
   ];
   for (const c of candidates) {
-    if (existsSync10(join24(c, "commands")) || existsSync10(join24(c, "routers")))
+    if (existsSync11(join25(c, "commands")) || existsSync11(join25(c, "routers")))
       return c;
   }
   return null;
@@ -5391,19 +5673,19 @@ function resolveTemplatesDir() {
 async function installCommandTemplates(repoRoot, templatesDir) {
   if (!templatesDir)
     return [];
-  const commandsDir = join24(templatesDir, "commands");
-  if (!existsSync10(commandsDir))
+  const commandsDir = join25(templatesDir, "commands");
+  if (!existsSync11(commandsDir))
     return [];
-  const destDir = join24(repoRoot, ".claude", "commands");
-  await mkdir7(destDir, { recursive: true });
+  const destDir = join25(repoRoot, ".claude", "commands");
+  await mkdir8(destDir, { recursive: true });
   const written = [];
   for (const name of await readdir15(commandsDir)) {
     if (!name.endsWith(".md"))
       continue;
-    const dest = join24(destDir, name);
-    if (existsSync10(dest))
+    const dest = join25(destDir, name);
+    if (existsSync11(dest))
       continue;
-    await copyFile2(join24(commandsDir, name), dest);
+    await copyFile2(join25(commandsDir, name), dest);
     written.push(dest);
   }
   return written;
@@ -5418,16 +5700,16 @@ var ROUTER_FILES = [
 async function installRouterTemplates(repoRoot, templatesDir) {
   if (!templatesDir)
     return [];
-  const routersDir = join24(templatesDir, "routers");
-  if (!existsSync10(routersDir))
+  const routersDir = join25(templatesDir, "routers");
+  if (!existsSync11(routersDir))
     return [];
   const written = [];
   for (const name of ROUTER_FILES) {
-    const src = join24(routersDir, name);
-    if (!existsSync10(src))
+    const src = join25(routersDir, name);
+    if (!existsSync11(src))
       continue;
-    const dest = join24(repoRoot, name);
-    if (existsSync10(dest))
+    const dest = join25(repoRoot, name);
+    if (existsSync11(dest))
       continue;
     await copyFile2(src, dest);
     written.push(dest);
@@ -5436,15 +5718,15 @@ async function installRouterTemplates(repoRoot, templatesDir) {
 }
 async function seedInstanceConfig(repoRoot, templatesDir) {
   const written = [];
-  const agentDir = join24(repoRoot, ".agent");
-  const vortexJson = join24(agentDir, "vortex.json");
-  if (!existsSync10(vortexJson)) {
-    await mkdir7(agentDir, { recursive: true });
-    const tmpl = templatesDir ? join24(templatesDir, "config", "vortex.json") : null;
-    if (tmpl && existsSync10(tmpl)) {
+  const agentDir = join25(repoRoot, ".agent");
+  const vortexJson = join25(agentDir, "vortex.json");
+  if (!existsSync11(vortexJson)) {
+    await mkdir8(agentDir, { recursive: true });
+    const tmpl = templatesDir ? join25(templatesDir, "config", "vortex.json") : null;
+    if (tmpl && existsSync11(tmpl)) {
       await copyFile2(tmpl, vortexJson);
     } else {
-      await writeFile10(vortexJson, JSON.stringify({
+      await writeFile11(vortexJson, JSON.stringify({
         autoRecord: {
           sessionStart: true,
           worklog: true,
@@ -5459,9 +5741,9 @@ async function seedInstanceConfig(repoRoot, templatesDir) {
     }
     written.push(vortexJson);
   }
-  const pkgPath = join24(repoRoot, "package.json");
-  if (!existsSync10(pkgPath)) {
-    await writeFile10(pkgPath, JSON.stringify({
+  const pkgPath = join25(repoRoot, "package.json");
+  if (!existsSync11(pkgPath)) {
+    await writeFile11(pkgPath, JSON.stringify({
       name: "vortex-instance",
       version: "0.0.0",
       private: true,
@@ -5478,9 +5760,9 @@ async function runInit(input, tokens) {
   const templatesDir = resolveTemplatesDir();
   const requiredDirs = ["_memory", "worklog", "decision-log", "hubs", "inbox", "runbooks"];
   for (const d2 of requiredDirs) {
-    const p = join24(dataDir, d2);
-    if (!existsSync10(p))
-      await mkdir7(p, { recursive: true });
+    const p = join25(dataDir, d2);
+    if (!existsSync11(p))
+      await mkdir8(p, { recursive: true });
   }
   const scaffolded = [];
   try {
@@ -5491,8 +5773,8 @@ async function runInit(input, tokens) {
     scaffolded.push(...await seedInstanceConfig(repoRoot, templatesDir));
   } catch {
   }
-  const profilePath = join24(dataDir, "_memory", "user_profile.md");
-  if (existsSync10(profilePath) && !args.force) {
+  const profilePath = join25(dataDir, "_memory", "user_profile.md");
+  if (existsSync11(profilePath) && !args.force) {
     const manifestNotes = [];
     try {
       const m2 = await writeOwnershipManifest(input.context, templatesDir);
@@ -5517,24 +5799,18 @@ async function runInit(input, tokens) {
     };
   }
   const missing = [];
-  if (!args.name) {
+  if (!args.name?.trim()) {
     missing.push({
       name: "name",
       prompt: 'What name or handle should VortEX use for you? (e.g. "Alex" or "team-lead")'
     });
   }
-  if (!args.role) {
+  if (!args.role?.trim()) {
     missing.push({
       name: "role",
       prompt: 'What is your main role in one word? (e.g. "engineer", "researcher", "writer")'
     });
   }
-  if (!args.task) {
-    missing.push({
-      name: "task",
-      prompt: "What is one thing you're working on right now? (one sentence \u2014 this becomes your first worklog seed)"
-    });
-  }
   if (missing.length > 0) {
     return {
       subcommand: "init",
@@ -5543,7 +5819,8 @@ async function runInit(input, tokens) {
       missingInputs: missing,
       nextActions: [
         "Ask the user the prompts in `missingInputs`, then re-run with the answers:",
-        '  /vortex init --name "<name>" --role "<role>" --task "<task>"',
+        '  /vortex init --name "<name>" --role "<role>"',
+        'Optional: add --task "<one sentence>" to seed your first worklog; omit it and it defaults to "Setting up my VortEX instance".',
         "Optional: append `--force` to overwrite an already-initialized instance."
       ]
     };
@@ -5555,22 +5832,25 @@ async function runInit(input, tokens) {
     const names = scaffolded.map((p) => p.replace(repoRoot, ".").replace(/\\/g, "/"));
     scaffoldNotes.push(`Seeded instance scaffolding: ${names.join(", ")}.`);
   }
-  await writeFile10(profilePath, renderUserProfile(args.name, args.role, args.task, today2), "utf8");
+  const name = args.name.trim();
+  const role = args.role.trim();
+  const task = args.task?.trim() || DEFAULT_INIT_TASK;
+  await writeFile11(profilePath, renderUserProfile(name, role, task, today2), "utf8");
   created.push(profilePath);
   const [year, month] = today2.split("-");
-  const worklogDir = join24(dataDir, "worklog", year, month);
-  await mkdir7(worklogDir, { recursive: true });
-  const worklogPath = join24(worklogDir, `${today2}-vortex-init.md`);
-  await writeFile10(worklogPath, renderFirstWorklog(args.name, args.role, args.task, today2), "utf8");
+  const worklogDir = join25(dataDir, "worklog", year, month);
+  await mkdir8(worklogDir, { recursive: true });
+  const worklogPath = join25(worklogDir, `${today2}-vortex-init.md`);
+  await writeFile11(worklogPath, renderFirstWorklog(name, role, task, today2), "utf8");
   created.push(worklogPath);
   const hookNotes = [];
   try {
-    const settingsPath = join24(input.context.repoRoot, ".claude", "settings.json");
-    const existingText = existsSync10(settingsPath) ? await readFile19(settingsPath, "utf8") : null;
+    const settingsPath = join25(input.context.repoRoot, ".claude", "settings.json");
+    const existingText = existsSync11(settingsPath) ? await readFile20(settingsPath, "utf8") : null;
     const { settings, added, alreadyWired } = ensureVortexHooks(parseSettings(existingText));
     if (!alreadyWired) {
-      await mkdir7(join24(input.context.repoRoot, ".claude"), { recursive: true });
-      await writeFile10(settingsPath, serializeSettings(settings), "utf8");
+      await mkdir8(join25(input.context.repoRoot, ".claude"), { recursive: true });
+      await writeFile11(settingsPath, serializeSettings(settings), "utf8");
       created.push(settingsPath);
       hookNotes.push(`Wired ${added.join(" + ")} hook(s) into .claude/settings.json \u2014 the VortEX boot report runs automatically at session start.`);
     } else {
@@ -5606,8 +5886,10 @@ async function runInit(input, tokens) {
     "  /log <one-line update>       \u2014 append a section to today's worklog",
     "  /decision <slug> <title>     \u2014 record a decision",
     "  /session-start               \u2014 daily start-of-session report",
-    `Open ${worklogPath} to see your first worklog \u2014 it already names "${args.task}".`,
-    "Hubs grow organically: once 3+ categories accumulate on the same topic, create `hubs/_HUB-<topic>.md` to cross-link them."
+    `Open ${worklogPath} to see your first worklog \u2014 it already names "${task}".`,
+    "Hubs grow organically: once 3+ categories accumulate on the same topic, create `hubs/_HUB-<topic>.md` to cross-link them.",
+    "",
+    "\u{1F310} Optional \u2014 use VortEX from ANY folder, not just this one? Run `vortex global-setup` (adds an instance pointer + session hook to your global ~/.claude, merge-safe). Skip with `vortex global-setup --decline`."
   ];
   const importPrompt = [];
   if (externalFolders && externalFolders.length > 0) {
@@ -5630,10 +5912,77 @@ async function runInit(input, tokens) {
     nextActions: [...baseNext, ...importPrompt]
   };
 }
+async function runGlobalSetup(input, tokens) {
+  const instanceRoot = input.context.repoRoot;
+  if (tokens.includes("--decline")) {
+    try {
+      const statePath = await recordGlobalSetupDecline();
+      return {
+        subcommand: "global-setup",
+        status: "declined",
+        created: [],
+        modified: [statePath],
+        skipped: [],
+        nextActions: [
+          "Noted \u2014 VortEX will not offer global usage again.",
+          "Changed your mind later? Run `vortex global-setup` any time to enable it."
+        ]
+      };
+    } catch (e) {
+      return globalSetupError(`Could not record the decline: ${e?.message ?? e}`);
+    }
+  }
+  if (!isSafeInstanceRoot(instanceRoot)) {
+    return globalSetupError(`Refusing to enable global usage: "${instanceRoot}" is not a valid initialized VortEX instance (need an absolute path containing .agent/vortex.json or data/_memory/user_profile.md, and no newlines). Run this from your instance folder, or pass VORTEX_REPO_ROOT=<instance path>.`);
+  }
+  try {
+    const { created, modified, skipped } = await applyGlobalSetup({ instanceRoot });
+    const changed = created.length + modified.length;
+    return {
+      subcommand: "global-setup",
+      status: "completed",
+      created,
+      modified,
+      skipped,
+      nextActions: [
+        changed > 0 ? "Global usage enabled \u2014 VortEX now works from any folder." : "Global usage was already set up \u2014 nothing to change.",
+        "Open a NEW agent session (in any folder) so the global rules + session hook load.",
+        `Records still go to this instance: ${instanceRoot}`,
+        "Note: the global session hook fires only where `@vortex-os/base` resolves. If a folder has no local install and the report doesn't appear, run `npm i -g @vortex-os/base` once \u2014 the ~/.claude/CLAUDE.md pointer works regardless.",
+        "Undo: delete the VortEX block from ~/.claude/CLAUDE.md and the VortEX hooks from ~/.claude/settings.json."
+      ]
+    };
+  } catch (e) {
+    return globalSetupError(`Global setup failed: ${e?.message ?? e}. Your ~/.claude was not left mis-routing (the pointer is written before the hook).`);
+  }
+}
+function globalSetupError(message) {
+  return {
+    subcommand: "global-setup",
+    status: "error",
+    created: [],
+    modified: [],
+    skipped: [],
+    nextActions: [message]
+  };
+}
 async function runUpdate(input, tokens) {
   const dryRun = tokens.includes("--dry-run");
+  const adopt = parseAdoptArgs(tokens);
   const templatesDir = resolveTemplatesDir();
-  return runTemplatesUpdate(input.context, templatesDir, { dryRun });
+  return runTemplatesUpdate(input.context, templatesDir, {
+    dryRun,
+    adopt: adopt.size > 0 ? adopt : void 0
+  });
+}
+function parseAdoptArgs(tokens) {
+  const adopt = /* @__PURE__ */ new Set();
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i] === "--adopt" && i + 1 < tokens.length) {
+      adopt.add(tokens[++i].replace(/\\/g, "/").replace(/^\.\//, ""));
+    }
+  }
+  return adopt;
 }
 function parseInitArgs(tokens) {
   const args = {};
@@ -5749,18 +6098,18 @@ var COUNT_KEY_TO_DIR = {
 };
 async function runStatus(input) {
   const { dataDir } = input.context;
-  const profilePath = join24(dataDir, "_memory", "user_profile.md");
-  const initialized = existsSync10(profilePath);
+  const profilePath = join25(dataDir, "_memory", "user_profile.md");
+  const initialized = existsSync11(profilePath);
   const counts = {
-    memory: await safeCount(join24(dataDir, "_memory"), false),
-    worklog: await safeCount(join24(dataDir, "worklog"), true),
-    decisionLog: await safeCount(join24(dataDir, "decision-log"), false),
-    runbooks: await safeCount(join24(dataDir, "runbooks"), false),
-    hubs: await safeCount(join24(dataDir, "hubs"), false)
+    memory: await safeCount(join25(dataDir, "_memory"), false),
+    worklog: await safeCount(join25(dataDir, "worklog"), true),
+    decisionLog: await safeCount(join25(dataDir, "decision-log"), false),
+    runbooks: await safeCount(join25(dataDir, "runbooks"), false),
+    hubs: await safeCount(join25(dataDir, "hubs"), false)
   };
   let latestWorklog;
   try {
-    const store = new WorklogStore(join24(dataDir, "worklog"));
+    const store = new WorklogStore(join25(dataDir, "worklog"));
     const latest = await store.getLatest();
     if (latest) {
       latestWorklog = {
@@ -5774,7 +6123,7 @@ async function runStatus(input) {
   let profile;
   if (initialized) {
     try {
-      const raw = await readFile19(profilePath, "utf8");
+      const raw = await readFile20(profilePath, "utf8");
       const { body } = parseFrontmatter(raw);
       profile = extractProfile(body);
     } catch {
@@ -5787,13 +6136,13 @@ async function runStatus(input) {
   for (const [key, count] of Object.entries(counts)) {
     if (count === 0) {
       const dirName = COUNT_KEY_TO_DIR[key];
-      const dirPath = join24(dataDir, dirName);
-      missing.push(existsSync10(dirPath) ? `${dirName}/ is empty` : `${dirName}/ does not exist`);
+      const dirPath = join25(dataDir, dirName);
+      missing.push(existsSync11(dirPath) ? `${dirName}/ is empty` : `${dirName}/ does not exist`);
     }
   }
   const nextActions = [];
   if (!initialized) {
-    nextActions.push("Run `/vortex init --name <name> --role <role> --task <task>` to set up this instance.");
+    nextActions.push('Run `/vortex init --name <name> --role <role>` to set up this instance (optional: add --task "<first focus>").');
   } else {
     nextActions.push("Run `/session-start` for a fuller session-opening report.", "Run `/log <section-title>` to append a section to today's worklog.");
     if (counts.decisionLog === 0) {
@@ -5823,7 +6172,7 @@ function extractProfile(body) {
   return out;
 }
 async function safeCount(dir, recursive) {
-  if (!existsSync10(dir))
+  if (!existsSync11(dir))
     return 0;
   try {
     return await countMarkdown2(dir, recursive);
@@ -5847,7 +6196,7 @@ async function countMarkdown2(dir, recursive) {
     } else if (e.isDirectory() && recursive) {
       if (e.name.startsWith(".") || e.name.startsWith("_"))
         continue;
-      total += await countMarkdown2(join24(dir, e.name), recursive);
+      total += await countMarkdown2(join25(dir, e.name), recursive);
     }
   }
   return total;
@@ -5982,7 +6331,7 @@ async function runImport(input, tokens) {
       ]
     };
   }
-  if (!existsSync10(args.from)) {
+  if (!existsSync11(args.from)) {
     return {
       subcommand: "import",
       status: "source-missing",
@@ -6016,9 +6365,9 @@ async function runImport(input, tokens) {
   const systemDirsCreated = [];
   if (!args.dryRun) {
     for (const d2 of systemDirs) {
-      const p = join24(dataDir, d2);
-      if (!existsSync10(p)) {
-        await mkdir7(p, { recursive: true });
+      const p = join25(dataDir, d2);
+      if (!existsSync11(p)) {
+        await mkdir8(p, { recursive: true });
         systemDirsCreated.push(d2);
       }
     }
@@ -6113,7 +6462,7 @@ async function runImport(input, tokens) {
 async function walkAndImport(rootSource, currentDir, dataDir, dryRun, stats) {
   const entries = await readdir15(currentDir, { withFileTypes: true });
   for (const e of entries) {
-    const sourcePath = join24(currentDir, e.name);
+    const sourcePath = join25(currentDir, e.name);
     if (e.isDirectory()) {
       if (IMPORT_SKIP_DIRS.has(e.name.toLowerCase()))
         continue;
@@ -6134,7 +6483,7 @@ async function walkAndImport(rootSource, currentDir, dataDir, dryRun, stats) {
         continue;
       }
       stats.totalFiles++;
-      const raw = await readFile19(sourcePath, "utf8");
+      const raw = await readFile20(sourcePath, "utf8");
       const parsed = parseFrontmatter(raw);
       const hasFrontmatter = Object.keys(parsed.frontmatter).length > 0;
       const category = classifyFile(sourcePath, rootSource, e.name, parsed.frontmatter);
@@ -6148,13 +6497,13 @@ async function walkAndImport(rootSource, currentDir, dataDir, dryRun, stats) {
         const fileStat = await stat7(sourcePath);
         const enhanced = enhanceFrontmatter(parsed.frontmatter, category, fileStat.birthtime, fileStat.mtime, sourcePath, rootSource);
         const targetPath = computeTargetPath(category, sourcePath, rootSource, dataDir, e.name);
-        await mkdir7(dirname5(targetPath), { recursive: true });
+        await mkdir8(dirname5(targetPath), { recursive: true });
         const out = serializeFrontmatter({
           frontmatter: enhanced,
           body: parsed.body
         });
         try {
-          await writeFile10(targetPath, out, { encoding: "utf8", flag: "wx" });
+          await writeFile11(targetPath, out, { encoding: "utf8", flag: "wx" });
           stats.copied++;
         } catch (e2) {
           if (e2.code === "EEXIST") {
@@ -6187,8 +6536,8 @@ async function importAttachment(sourcePath, relPath, filename, dataDir, dryRun,
     stats.importedExtensions.add(ext);
   if (dryRun)
     return;
-  const targetPath = join24(dataDir, relPath);
-  await mkdir7(dirname5(targetPath), { recursive: true });
+  const targetPath = join25(dataDir, relPath);
+  await mkdir8(dirname5(targetPath), { recursive: true });
   try {
     await copyFile2(sourcePath, targetPath, constants.COPYFILE_EXCL);
     stats.attachmentsCopied++;
@@ -6251,27 +6600,27 @@ function computeTargetPath(category, sourcePath, rootSource, dataDir, filename)
   const mdName = withMdExtension(filename);
   if (category === "preserved") {
     const relPath = withMdExtension(sourcePath.substring(rootSource.length).replace(/^[/\\]/, ""));
-    return join24(dataDir, relPath);
+    return join25(dataDir, relPath);
   }
   if (category === "worklog") {
     const match = mdName.match(/^(\d{4})-(\d{2})-/);
     if (match) {
-      return join24(dataDir, "worklog", match[1], match[2], mdName);
+      return join25(dataDir, "worklog", match[1], match[2], mdName);
     }
     const d2 = /* @__PURE__ */ new Date();
     const y2 = String(d2.getFullYear());
     const m2 = String(d2.getMonth() + 1).padStart(2, "0");
-    return join24(dataDir, "worklog", y2, m2, mdName);
+    return join25(dataDir, "worklog", y2, m2, mdName);
   }
   if (category === "decisionLog")
-    return join24(dataDir, "decision-log", mdName);
+    return join25(dataDir, "decision-log", mdName);
   if (category === "runbooks")
-    return join24(dataDir, "runbooks", mdName);
+    return join25(dataDir, "runbooks", mdName);
   if (category === "hubs")
-    return join24(dataDir, "hubs", mdName);
+    return join25(dataDir, "hubs", mdName);
   if (category === "memory")
-    return join24(dataDir, "_memory", mdName);
-  return join24(dataDir, mdName);
+    return join25(dataDir, "_memory", mdName);
+  return join25(dataDir, mdName);
 }
 function withMdExtension(name) {
   const ext = extname11(name);
@@ -6418,14 +6767,14 @@ async function checkControlBytes(dataDir) {
       return;
     }
     for (const e of entries) {
-      const p = join24(dir, e.name);
+      const p = join25(dir, e.name);
       if (e.isDirectory()) {
         if (SKIP_DIRS.has(e.name))
           continue;
         await walk5(p);
       } else if (e.isFile() && CONTROL_SCAN_EXT.has(extname11(e.name).toLowerCase())) {
         try {
-          const buf = await readFile19(p);
+          const buf = await readFile20(p);
           for (let i = 0; i < buf.length; i++) {
             const x2 = buf[i];
             if (x2 < 32 && x2 !== 9 && x2 !== 10 && x2 !== 13) {
@@ -6452,7 +6801,7 @@ async function checkControlBytes(dataDir) {
   };
 }
 function checkSystemDirs(dataDir) {
-  const missing = DOCTOR_SYSTEM_DIRS.filter((d2) => !existsSync10(join24(dataDir, d2)));
+  const missing = DOCTOR_SYSTEM_DIRS.filter((d2) => !existsSync11(join25(dataDir, d2)));
   if (missing.length === 0) {
     return {
       id: "system-dirs",
@@ -6468,8 +6817,8 @@ function checkSystemDirs(dataDir) {
   };
 }
 function checkUserProfile(dataDir) {
-  const profilePath = join24(dataDir, "_memory", "user_profile.md");
-  if (existsSync10(profilePath)) {
+  const profilePath = join25(dataDir, "_memory", "user_profile.md");
+  if (existsSync11(profilePath)) {
     return {
       id: "user-profile",
       label: "user_profile.md exists",
@@ -6486,11 +6835,11 @@ function checkUserProfile(dataDir) {
 async function checkIndexes(dataDir) {
   const missing = [];
   for (const d2 of DOCTOR_SYSTEM_DIRS) {
-    const dirPath = join24(dataDir, d2);
-    if (!existsSync10(dirPath))
+    const dirPath = join25(dataDir, d2);
+    if (!existsSync11(dirPath))
       continue;
-    const indexPath = join24(dirPath, "_INDEX.md");
-    if (!existsSync10(indexPath))
+    const indexPath = join25(dirPath, "_INDEX.md");
+    if (!existsSync11(indexPath))
       missing.push(`${d2}/_INDEX.md`);
   }
   if (missing.length === 0) {
@@ -6523,7 +6872,7 @@ async function collectAttachmentExtensions(dataDir) {
         if (e.name.startsWith(".") || e.name === "_session-archive" || e.name === "node_modules") {
           continue;
         }
-        stack.push(join24(current, e.name));
+        stack.push(join25(current, e.name));
       } else if (e.isFile()) {
         const ext = extname11(e.name);
         if (ext && ext.toLowerCase() !== ".md")
@@ -6620,8 +6969,8 @@ async function checkFrontmatterLint(dataDir, additionalExtensions = []) {
   }
 }
 async function checkRunbookAging(dataDir) {
-  const runbooksDir = join24(dataDir, "runbooks");
-  if (!existsSync10(runbooksDir)) {
+  const runbooksDir = join25(dataDir, "runbooks");
+  if (!existsSync11(runbooksDir)) {
     return {
       id: "runbook-aging",
       label: `runbooks tested within ${RUNBOOK_AGING_DAYS} days`,
@@ -6641,8 +6990,8 @@ async function checkRunbookAging(dataDir) {
         continue;
       }
       total++;
-      const filePath = join24(runbooksDir, e.name);
-      const raw = await readFile19(filePath, "utf8");
+      const filePath = join25(runbooksDir, e.name);
+      const raw = await readFile20(filePath, "utf8");
       const { frontmatter } = parseFrontmatter(raw);
       if (!frontmatter.last_tested) {
         stale.push(`${e.name} (no last_tested)`);
@@ -6704,8 +7053,8 @@ function checkNodeVersion() {
   };
 }
 async function checkGitRemote(repoRoot) {
-  const gitConfig = join24(repoRoot, ".git", "config");
-  if (!existsSync10(gitConfig)) {
+  const gitConfig = join25(repoRoot, ".git", "config");
+  if (!existsSync11(gitConfig)) {
     return {
       id: "git-remote",
       label: "git remote for sync",
@@ -6714,7 +7063,7 @@ async function checkGitRemote(repoRoot) {
     };
   }
   try {
-    const raw = await readFile19(gitConfig, "utf8");
+    const raw = await readFile20(gitConfig, "utf8");
     const match = raw.match(/\[remote "origin"\][\s\S]*?url\s*=\s*(.+)/);
     if (!match) {
       return {
@@ -6744,11 +7093,11 @@ async function detectExternalFolders(excludePath) {
   if (!home)
     return void 0;
   const candidates = [
-    join24(home, "Documents", "obsidian-vault"),
-    join24(home, "Documents", "notes"),
-    join24(home, "Documents", "Notebook"),
-    join24(home, "notes"),
-    join24(home, "Notes")
+    join25(home, "Documents", "obsidian-vault"),
+    join25(home, "Documents", "notes"),
+    join25(home, "Documents", "Notebook"),
+    join25(home, "notes"),
+    join25(home, "Notes")
   ];
   const excludeNorm = excludePath.replace(/[/\\]+$/, "");
   const found = [];
@@ -6757,7 +7106,7 @@ async function detectExternalFolders(excludePath) {
     if (candNorm === excludeNorm || candNorm.startsWith(excludeNorm + "/") || candNorm.startsWith(excludeNorm + "\\") || excludeNorm.startsWith(candNorm + "/") || excludeNorm.startsWith(candNorm + "\\")) {
       continue;
     }
-    if (!existsSync10(candidate))
+    if (!existsSync11(candidate))
       continue;
     let mdCount = 0;
     try {
@@ -7094,22 +7443,22 @@ function createRitualRegistry(options) {
 
 // ../plugins/session-rituals/dist/cli-dispatch.js
 import { execFileSync, spawn as spawn2 } from "child_process";
-import { existsSync as existsSync14, readFileSync as readFileSync3, mkdirSync, openSync, writeSync, closeSync, linkSync, rmSync, statSync } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync4, mkdirSync, openSync, writeSync, closeSync, linkSync, rmSync, statSync } from "fs";
 import { createRequire } from "module";
 import { hostname } from "os";
-import { join as join29 } from "path";
+import { isAbsolute as isAbsolute5, join as join30 } from "path";
 
 // ../plugins/session-rituals/dist/update-check.js
 import { execSync } from "child_process";
-import { existsSync as existsSync11, readFileSync as readFileSync2 } from "fs";
-import { join as join25 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync3 } from "fs";
+import { join as join26 } from "path";
 var PKG = "@vortex-os/base";
 var NPM_TIMEOUT_MS = 4e3;
 function readInstalledBaseVersion(templatesDir = resolveTemplatesDir()) {
   if (!templatesDir)
     return null;
   try {
-    const m2 = JSON.parse(readFileSync2(join25(templatesDir, "manifest.json"), "utf8"));
+    const m2 = JSON.parse(readFileSync3(join26(templatesDir, "manifest.json"), "utf8"));
     return typeof m2.baseVersion === "string" && parseCore(m2.baseVersion) ? m2.baseVersion.trim() : null;
   } catch {
     return null;
@@ -7181,8 +7530,8 @@ function isStableUpdate(latest, installed) {
   return compareSemver(latest, installed) === 1;
 }
 function buildInstallCommand(repoRoot) {
-  const has = (f) => existsSync11(join25(repoRoot, f));
-  const local = existsSync11(join25(repoRoot, "node_modules", "@vortex-os", "base"));
+  const has = (f) => existsSync12(join26(repoRoot, f));
+  const local = existsSync12(join26(repoRoot, "node_modules", "@vortex-os", "base"));
   let installPart;
   if (!local) {
     installPart = `npm i -g ${PKG}@latest`;
@@ -7210,9 +7559,9 @@ function checkBaseUpdate(ctx) {
 }
 
 // ../plugins/session-rituals/dist/session-start-report.js
-import { existsSync as existsSync12 } from "fs";
-import { readdir as readdir16, readFile as readFile20, stat as stat8 } from "fs/promises";
-import { join as join26 } from "path";
+import { existsSync as existsSync13 } from "fs";
+import { readdir as readdir16, readFile as readFile21, stat as stat8 } from "fs/promises";
+import { join as join27 } from "path";
 var COUNTED_DIRS2 = ["_memory", "worklog", "decision-log"];
 var DEFAULT_GAP_WINDOW_DAYS = 30;
 var BOOT_BANNER = String.raw`
@@ -7226,8 +7575,8 @@ async function collectSessionStartReport(ctx, opts) {
   const counts = {};
   const missing = [];
   for (const name of COUNTED_DIRS2) {
-    const dir = join26(ctx.dataDir, name);
-    if (!existsSync12(dir)) {
+    const dir = join27(ctx.dataDir, name);
+    if (!existsSync13(dir)) {
       missing.push(name);
       counts[name] = 0;
       continue;
@@ -7237,7 +7586,7 @@ async function collectSessionStartReport(ctx, opts) {
   const { recent, dates, latestBody } = await scanWorklog(ctx.dataDir);
   const cutoff = isoDate(addDays(now, -(opts?.gapWindowDays ?? DEFAULT_GAP_WINDOW_DAYS)));
   const recentWorklogDates = dates.filter((d2) => d2 >= cutoff);
-  const mem = await scanMemoryTiers(join26(ctx.dataDir, "_memory"));
+  const mem = await scanMemoryTiers(join27(ctx.dataDir, "_memory"));
   return {
     time: now.toISOString(),
     localTime: formatLocalTime(now),
@@ -7271,7 +7620,7 @@ async function scanMemoryTiers(memoryDir) {
   for (const e of entries) {
     if (!e.isFile() || !e.name.endsWith(".md"))
       continue;
-    const full = join26(memoryDir, e.name);
+    const full = join27(memoryDir, e.name);
     if (e.name === "_INDEX.md") {
       indexExists = true;
       try {
@@ -7285,7 +7634,7 @@ async function scanMemoryTiers(memoryDir) {
     memoryCount++;
     try {
       newestMemoryMs = Math.max(newestMemoryMs, (await stat8(full)).mtimeMs);
-      const raw = await readFile20(full, "utf8");
+      const raw = await readFile21(full, "utf8");
       const { frontmatter, body } = parseFrontmatter(raw);
       const scopeRaw = frontmatter?.["scope"];
       const scope = typeof scopeRaw === "string" ? scopeRaw.trim().toLowerCase() : "";
@@ -7312,9 +7661,12 @@ function detectWorklogGaps(commitDays, presentDates) {
   const present = new Set(presentDates);
   return [...new Set(commitDays)].filter((d2) => d2 && !present.has(d2)).sort();
 }
+function countUncommitted(porcelain) {
+  return porcelain.split(/\r?\n/).filter((l3) => l3.trim().length > 0).length;
+}
 function renderSessionStartReport(report, extras) {
   const lines = [
-    "> [VortEX session report \u2014 injected into your context only; the user has NOT seen it. Your first reply must relay the key points in the user's language: the time, what you were doing (\u2705 recent) and what's next (\u23ED\uFE0F), any update notices (\u{1F4E6}/\u2B06\uFE0F), and any \u26A0\uFE0F warnings. Don't assume this was displayed.]",
+    "> [VortEX session report \u2014 injected into your context only; the user has NOT seen it. Your first reply must relay the key points in the user's language: the time, what you were doing (\u2705 recent) and what's next (\u23ED\uFE0F), any update notices (\u{1F4E6}/\u2B06\uFE0F), any offer (\u{1F310}), any carried-over work (\u21A9\uFE0F), and any \u26A0\uFE0F warnings. Don't assume this was displayed.]",
     "",
     BOOT_BANNER,
     ""
@@ -7345,6 +7697,13 @@ function renderSessionStartReport(report, extras) {
   if (gaps.length) {
     lines.push(`- \u26A0\uFE0F work without a worklog: ${gaps.join(", ")} \u2014 backfill from that day's commits`);
   }
+  const carry = extras?.carryover;
+  if (carry?.interrupted) {
+    lines.push(carry.interrupted === "index.lock" ? `- \u26A0\uFE0F a git lock (\`index.lock\`) is present \u2014 another git process may be running, or it is stale from a crash; remove it if nothing is using git. \`/resume\` shows what stopped.` : `- \u26A0\uFE0F interrupted git op (\`${carry.interrupted}\`) \u2014 likely a crashed prior session; finish or abort it before new work. Run \`/resume\` to see what stopped.`);
+  }
+  if (carry && carry.uncommitted > 0) {
+    lines.push(`- \u21A9\uFE0F ${carry.uncommitted} uncommitted change(s) carried over from a prior session \u2014 run \`/resume\` if you're unsure they were meant to stay.`);
+  }
   const cu = extras?.catchUp;
   if (cu && (cu.ingestedLocal > 0 || cu.indexedPulled > 0 || cu.errors > 0)) {
     const parts = [];
@@ -7376,11 +7735,15 @@ function renderSessionStartReport(report, extras) {
   if (uc && uc.newer && uc.latest) {
     lines.push(`- \u2B06\uFE0F update available: ${uc.package} ${uc.installed ?? "?"} \u2192 ${uc.latest} (checked ${uc.registry}) \u2014 ask the user, then to apply: ${uc.command}`);
   }
+  if (extras?.globalSetupOffer) {
+    lines.push("- \u{1F310} use VortEX from any folder? \u2014 enable with `vortex global-setup` (adds an instance pointer + session hook to your global ~/.claude, merge-safe). Ask the user once; on no, run `vortex global-setup --decline` so it stops asking.");
+  }
   if (report.alwaysOnRules.length > 0) {
-    lines.push("", "\u2500\u2500\u2500 always-on rules (loaded every session) \u2500\u2500\u2500");
+    lines.push("", "<always_on_rules>", "\u2500\u2500\u2500 always-on rules (loaded every session) \u2500\u2500\u2500");
     for (const r of report.alwaysOnRules) {
       lines.push("", `### ${r.slug}`, r.body + (r.truncated ? "\n\u2026(truncated \u2014 keep always-on rules short)" : ""));
     }
+    lines.push("", "</always_on_rules>");
   }
   return lines.join("\n") + "\n";
 }
@@ -7399,14 +7762,14 @@ async function countMarkdown3(dir, recursive) {
     } else if (e.isDirectory() && recursive) {
       if (e.name.startsWith(".") || e.name.startsWith("_"))
         continue;
-      total += await countMarkdown3(join26(dir, e.name), recursive);
+      total += await countMarkdown3(join27(dir, e.name), recursive);
     }
   }
   return total;
 }
 async function scanWorklog(dataDir) {
-  const root = join26(dataDir, "worklog");
-  if (!existsSync12(root))
+  const root = join27(dataDir, "worklog");
+  if (!existsSync13(root))
     return { recent: null, dates: [], latestBody: "" };
   let bestRel = null;
   const dates = /* @__PURE__ */ new Set();
@@ -7420,7 +7783,7 @@ async function scanWorklog(dataDir) {
     for (const e of entries) {
       const childRel = rel ? `${rel}/${e.name}` : e.name;
       if (e.isDirectory()) {
-        await walk5(join26(absDir, e.name), childRel);
+        await walk5(join27(absDir, e.name), childRel);
       } else if (e.isFile()) {
         const m2 = e.name.match(/^(\d{4}-\d{2}-\d{2})-.+\.md$/);
         if (!m2)
@@ -7434,7 +7797,7 @@ async function scanWorklog(dataDir) {
   await walk5(root, "");
   if (bestRel === null)
     return { recent: null, dates: [...dates], latestBody: "" };
-  const { title, body } = await readWorklogTitleAndBody(join26(root, bestRel));
+  const { title, body } = await readWorklogTitleAndBody(join27(root, bestRel));
   return { recent: { path: `worklog/${bestRel}`, title }, dates: [...dates], latestBody: body };
 }
 var MAX_WORKLOG_READ_BYTES = 512 * 1024;
@@ -7445,7 +7808,7 @@ async function readWorklogTitleAndBody(absPath) {
     if ((await stat8(absPath)).size > MAX_WORKLOG_READ_BYTES) {
       return { title: fromName, body: "" };
     }
-    const raw = await readFile20(absPath, "utf8");
+    const raw = await readFile21(absPath, "utf8");
     const m2 = raw.match(/^#\s+(.+)$/m);
     return { title: m2 ? m2[1].trim() : fromName, body: raw };
   } catch {
@@ -7498,20 +7861,20 @@ function isoDate(d2) {
 }
 
 // ../plugins/session-rituals/dist/worklog-write.js
-import { mkdir as mkdir8, writeFile as writeFile11 } from "fs/promises";
-import { dirname as dirname6, join as join27 } from "path";
+import { mkdir as mkdir9, writeFile as writeFile12 } from "fs/promises";
+import { dirname as dirname6, join as join28 } from "path";
 async function ensureWorklogEntry(ctx, opts) {
   const date = isoDate2(opts?.now ?? /* @__PURE__ */ new Date());
   const keyword = (opts?.keyword ?? "worklog").trim() || "worklog";
-  const store = new WorklogStore(join27(ctx.dataDir, "worklog"));
+  const store = new WorklogStore(join28(ctx.dataDir, "worklog"));
   const existing = await store.get(date);
   if (existing) {
     return { path: existing.path, date: existing.date, keyword: existing.keyword, created: false };
   }
   const path = store.pathFor(date, keyword);
   const title = opts?.title ?? `${date} worklog`;
-  await mkdir8(dirname6(path), { recursive: true });
-  await writeFile11(path, renderWorklogFile(date, title, opts?.body ?? ""), "utf8");
+  await mkdir9(dirname6(path), { recursive: true });
+  await writeFile12(path, renderWorklogFile(date, title, opts?.body ?? ""), "utf8");
   return { path, date, keyword, created: true };
 }
 function renderWorklogFile(date, title, body) {
@@ -7536,10 +7899,10 @@ function isoDate2(d2) {
 }
 
 // ../plugins/session-rituals/dist/curate-cli.js
-import { existsSync as existsSync13 } from "fs";
+import { existsSync as existsSync14 } from "fs";
 import { createHash as createHash3 } from "crypto";
-import { readFile as readFile21, readdir as readdir17 } from "fs/promises";
-import { join as join28 } from "path";
+import { readFile as readFile22, readdir as readdir17 } from "fs/promises";
+import { join as join29 } from "path";
 var SYSTEM_META_DIRS3 = /* @__PURE__ */ new Set([
   "worklog",
   "decision-log",
@@ -7619,10 +7982,10 @@ function joinRel(...parts) {
 }
 async function runCurateCandidates(repoRoot, options) {
   const maxEntries = options?.maxEntries ?? 200;
-  const dataDir = join28(repoRoot, "data");
+  const dataDir = join29(repoRoot, "data");
   const candidates = [];
   let truncated = false;
-  if (existsSync13(dataDir)) {
+  if (existsSync14(dataDir)) {
     async function visit(absDir, relDir) {
       if (candidates.length >= maxEntries) {
         truncated = true;
@@ -7645,7 +8008,7 @@ async function runCurateCandidates(repoRoot, options) {
             continue;
           if (atRoot && (SYSTEM_META_DIRS3.has(e.name) || e.name.startsWith("_")))
             continue;
-          await visit(join28(absDir, e.name), joinRel(relDir, e.name));
+          await visit(join29(absDir, e.name), joinRel(relDir, e.name));
         } else if (e.isFile() && e.name.endsWith(".md")) {
           if (NON_DOC_FILES.has(e.name))
             continue;
@@ -7654,7 +8017,7 @@ async function runCurateCandidates(repoRoot, options) {
           let topic = null;
           let tags = [];
           try {
-            const raw = await readFile21(join28(absDir, e.name), "utf8");
+            const raw = await readFile22(join29(absDir, e.name), "utf8");
             const parsed = parseFrontmatter(raw);
             if (typeof parsed.frontmatter.topic === "string") {
               topic = parsed.frontmatter.topic.trim().toLowerCase();
@@ -7692,7 +8055,7 @@ async function runCuratePreview(repoRoot, payload, now = /* @__PURE__ */ new Dat
     };
   }
   try {
-    validateDataRelativePath(join28(repoRoot, "data"), v2.effectiveRelPath);
+    validateDataRelativePath(join29(repoRoot, "data"), v2.effectiveRelPath);
   } catch (e) {
     return {
       subcommand: "curate-preview",
@@ -7709,10 +8072,10 @@ async function runCuratePreview(repoRoot, payload, now = /* @__PURE__ */ new Dat
   let targetExists;
   let wouldDo;
   if (payload.action === "create-file") {
-    targetExists = existsSync13(join28(repoRoot, "data", v2.effectiveRelPath));
+    targetExists = existsSync14(join29(repoRoot, "data", v2.effectiveRelPath));
     wouldDo = targetExists ? `create-file at ${v2.effectiveRelPath} \u2014 but the file already EXISTS, so accept would REFUSE (no overwrite).` : `create a new document at data/${v2.effectiveRelPath}.`;
   } else {
-    targetExists = existsSync13(join28(repoRoot, "data", v2.effectiveRelPath));
+    targetExists = existsSync14(join29(repoRoot, "data", v2.effectiveRelPath));
     wouldDo = targetExists ? `append a "## ${payload.sectionHeader}" section to data/${v2.effectiveRelPath}.` : `append-section to data/${v2.effectiveRelPath} \u2014 but the file does NOT exist, so accept would FAIL (append-section never creates).`;
   }
   const nextActions = [];
@@ -7815,7 +8178,7 @@ async function runCurateDecline(repoRoot, payload, now = /* @__PURE__ */ new Dat
 }
 
 // ../plugins/session-rituals/dist/cli-dispatch.js
-var VORTEX_SUBCOMMANDS = ["init", "status", "import", "doctor", "update", "sync"];
+var VORTEX_SUBCOMMANDS = ["init", "status", "import", "doctor", "update", "sync", "global-setup"];
 async function buildRegistry() {
   try {
     const { vector } = await import("@vortex-os/memory-extended");
@@ -7825,7 +8188,16 @@ async function buildRegistry() {
   }
 }
 function resolveRepoRoot() {
-  return process.env.VORTEX_REPO_ROOT?.trim() || process.cwd();
+  const override = process.env.VORTEX_REPO_ROOT?.trim();
+  if (override)
+    return override;
+  const cwd = process.cwd();
+  if (isInstanceRoot(cwd))
+    return cwd;
+  const pointer = readGlobalInstancePointer();
+  if (pointer)
+    return pointer;
+  return cwd;
 }
 function requote(token) {
   if (!/\s/.test(token))
@@ -7834,6 +8206,11 @@ function requote(token) {
     return `'${token}'`;
   return `"${token.replace(/"/g, "")}"`;
 }
+function argvToSlash(argv) {
+  const name = argv[0] ?? "";
+  const body = argv.slice(1).map(requote).join(" ");
+  return `/${name} ${body}`.trim();
+}
 function readCuratePayload(args) {
   let raw = null;
   for (let i = 0; i < args.length; i++) {
@@ -7843,13 +8220,13 @@ function readCuratePayload(args) {
       break;
     }
     if (t === "--payload-file" && i + 1 < args.length) {
-      raw = readFileSync3(args[++i], "utf8");
+      raw = readFileSync4(args[++i], "utf8");
       break;
     }
   }
   if (raw === null) {
     try {
-      raw = readFileSync3(0, "utf8");
+      raw = readFileSync4(0, "utf8");
     } catch {
       raw = "";
     }
@@ -7917,7 +8294,7 @@ Instance shortcuts (also available as \`/vortex <sub>\`):
   status \u2014  instance state report
   import \u2014  bring an existing notes folder into data/
   doctor \u2014  health diagnosis
-  update \u2014  refresh framework templates from the installed package (hash-guarded; --dry-run to preview)
+  update \u2014  refresh framework templates from the installed package (hash-guarded; --dry-run to preview; --adopt <path> to re-adopt a file you edited)
 
 Usage: vortex <command> [args...]
 `);
@@ -7925,10 +8302,14 @@ Usage: vortex <command> [args...]
     }
     const name = argv[0];
     const isVortexSub = VORTEX_SUBCOMMANDS.includes(name);
-    const body = (isVortexSub ? argv : argv.slice(1)).map(requote).join(" ");
-    const slash = isVortexSub ? `/vortex ${body}` : `/${name} ${body}`;
     const context = makeContext(repoRoot);
-    const result = await runSlash(slash.trim(), { registry, context });
+    if (isVortexSub || name === "vortex") {
+      const subArgv = isVortexSub ? argv : argv.slice(1);
+      const result2 = await runSlashArgv("vortex", subArgv, { registry, context });
+      out(JSON.stringify(result2, null, 2) + "\n");
+      return 0;
+    }
+    const result = await runSlash(argvToSlash(argv), { registry, context });
     out(JSON.stringify(result, null, 2) + "\n");
     return 0;
   } catch (e) {
@@ -7973,12 +8354,12 @@ function memoryExtendedPresent() {
 }
 var VECTORIZE_LOCK_TTL_MS = 6 * 60 * 60 * 1e3;
 function vectorizeLockPath(ctx) {
-  return join29(ctx.dataDir, "_indexes", ".vectorize.lock");
+  return join30(ctx.dataDir, "_indexes", ".vectorize.lock");
 }
 function vectorizeSetupInProgress(ctx) {
   const lock = vectorizeLockPath(ctx);
   try {
-    if (!existsSync14(lock))
+    if (!existsSync15(lock))
       return false;
     return Date.now() - statSync(lock).mtimeMs < VECTORIZE_LOCK_TTL_MS;
   } catch {
@@ -7999,9 +8380,9 @@ function spawnVectorizeSetup(repoRoot) {
 }
 async function runVectorizeSetup(repoRoot, out, err) {
   const ctx = makeContext(repoRoot);
-  const indexDir = join29(ctx.dataDir, "_indexes");
-  const finalDb = join29(indexDir, "memory.sqlite");
-  if (existsSync14(finalDb)) {
+  const indexDir = join30(ctx.dataDir, "_indexes");
+  const finalDb = join30(indexDir, "memory.sqlite");
+  if (existsSync15(finalDb)) {
     out("recall index already present \u2014 nothing to do\n");
     return;
   }
@@ -8032,7 +8413,7 @@ async function runVectorizeSetup(repoRoot, out, err) {
       return;
     }
   }
-  const tmpDb = join29(indexDir, `memory.sqlite.building-${process.pid}`);
+  const tmpDb = join30(indexDir, `memory.sqlite.building-${process.pid}`);
   const tmpSidecars = [tmpDb + "-wal", tmpDb + "-shm", tmpDb + "-journal"];
   const cleanTmp = () => {
     rmSync(tmpDb, { force: true });
@@ -8042,7 +8423,7 @@ async function runVectorizeSetup(repoRoot, out, err) {
   let tokenWritten = false;
   const releaseLock = () => {
     try {
-      const cur = existsSync14(lockPath) ? readFileSync3(lockPath, "utf8").trim() : "";
+      const cur = existsSync15(lockPath) ? readFileSync4(lockPath, "utf8").trim() : "";
       if (cur === token || cur === "" && !tokenWritten)
         rmSync(lockPath, { force: true });
     } catch {
@@ -8055,7 +8436,7 @@ async function runVectorizeSetup(repoRoot, out, err) {
     } finally {
       closeSync(lockFd);
     }
-    if (existsSync14(finalDb)) {
+    if (existsSync15(finalDb)) {
       out("recall index already present \u2014 nothing to do\n");
       return;
     }
@@ -8071,7 +8452,7 @@ async function runVectorizeSetup(repoRoot, out, err) {
     } finally {
       db.close();
     }
-    if (existsSync14(tmpDb + "-wal")) {
+    if (existsSync15(tmpDb + "-wal")) {
       throw new Error("temp index retained a WAL sidecar after consolidation; refusing to publish");
     }
     try {
@@ -8119,6 +8500,7 @@ async function runSessionStart(repoRoot, out) {
     }
   } catch {
   }
+  const carryover = collectCarryover(repoRoot);
   const report = await collectSessionStartReport(ctx, { environment });
   let missingWorklogDays = [];
   try {
@@ -8138,7 +8520,7 @@ async function runSessionStart(repoRoot, out) {
   let vectorized = null;
   let vectorizeSetupStarted = false;
   if (config.autoRecord.vectorize) {
-    const dbExists = existsSync14(join29(ctx.dataDir, "_indexes", "memory.sqlite"));
+    const dbExists = existsSync15(join30(ctx.dataDir, "_indexes", "memory.sqlite"));
     const action = decideVectorizeAction({
       vectorizeOn: true,
       dbExists,
@@ -8182,6 +8564,12 @@ async function runSessionStart(repoRoot, out) {
     } catch {
     }
   }
+  let globalSetupOffer = false;
+  try {
+    const gs = inspectGlobalSetup(void 0, repoRoot);
+    globalSetupOffer = !gs.done && !gs.declined;
+  } catch {
+  }
   out(renderSessionStartReport(report, {
     git,
     missingWorklogDays,
@@ -8189,7 +8577,9 @@ async function runSessionStart(repoRoot, out) {
     vectorized: vectorized ?? void 0,
     vectorizeSetup: vectorizeSetupStarted || void 0,
     templateUpdate: templateUpdate ?? void 0,
-    updateCheck: updateCheck ?? void 0
+    updateCheck: updateCheck ?? void 0,
+    globalSetupOffer: globalSetupOffer || void 0,
+    carryover: carryover ?? void 0
   }));
 }
 async function runSessionEnd(repoRoot, out) {
@@ -8211,6 +8601,37 @@ function gitOut(cwd, gitArgs) {
     stdio: ["ignore", "pipe", "ignore"]
   });
 }
+function detectInterruptedGitOp(repoRoot) {
+  const markers = [
+    "MERGE_HEAD",
+    "rebase-merge",
+    "rebase-apply",
+    "CHERRY_PICK_HEAD",
+    "REVERT_HEAD",
+    "BISECT_LOG",
+    "index.lock"
+  ];
+  try {
+    const args = ["rev-parse", ...markers.flatMap((m2) => ["--git-path", m2])];
+    const resolved = gitOut(repoRoot, args).split(/\r?\n/).map((s) => s.trim());
+    for (let i = 0; i < markers.length; i++) {
+      const p = resolved[i];
+      if (p && existsSync15(isAbsolute5(p) ? p : join30(repoRoot, p)))
+        return markers[i];
+    }
+  } catch {
+  }
+  return null;
+}
+function collectCarryover(repoRoot) {
+  const interrupted = detectInterruptedGitOp(repoRoot);
+  let uncommitted = 0;
+  try {
+    uncommitted = countUncommitted(gitOut(repoRoot, ["status", "--porcelain"]));
+  } catch {
+  }
+  return uncommitted > 0 || interrupted ? { uncommitted, interrupted } : null;
+}
 function hadActivityToday(repoRoot) {
   try {
     const dirty = gitOut(repoRoot, ["status", "--porcelain"]).trim();
@@ -8228,23 +8649,23 @@ function resolveSessionEnvironment(ctx, config) {
   let environment = resolveEnvironment(config, {
     hostname: hostname(),
     env: process.env,
-    pathExists: existsSync14
+    pathExists: existsSync15
   });
   if (!environment)
     environment = process.env.VORTEX_ENV?.trim() || null;
   if (!environment) {
-    const envFile = join29(ctx.repoRoot, ".agent", "environment");
-    if (existsSync14(envFile)) {
-      environment = readFileSync3(envFile, "utf8").split(/\r?\n/)[0]?.trim() || null;
+    const envFile = join30(ctx.repoRoot, ".agent", "environment");
+    if (existsSync15(envFile)) {
+      environment = readFileSync4(envFile, "utf8").split(/\r?\n/)[0]?.trim() || null;
     }
   }
   return environment;
 }
 
 // ../plugins/session-rituals/dist/ambient-recall.js
-import { join as join30 } from "path";
+import { join as join31 } from "path";
 function defaultDbPath2(ctx) {
-  return join30(ctx.dataDir, "_indexes", "memory.sqlite");
+  return join31(ctx.dataDir, "_indexes", "memory.sqlite");
 }
 function createAmbientRecaller(ctx, options) {
   const resolveDb = options.dbPath ?? defaultDbPath2;