@dosu/cli 0.60.1 → 0.61.0

package/bin/dosu.js

@@ -1083,7 +1083,7 @@ function isNpxInvocation(channel = INSTALL_CHANNEL, env = process.env) {
 function getVersionString() {
   return `v${VERSION}`;
 }
-var VERSION = "0.60.1", INSTALL_CHANNEL = "npm";
+var VERSION = "0.61.0", INSTALL_CHANNEL = "npm";
 
 // src/debug/logger.ts
 import {
@@ -13800,7 +13800,7 @@ var init_conflicts = __esm(() => {
 });
 
 // src/telemetry/debug-id.ts
-var BUNDLE_DEBUG_ID_PLACEHOLDER = "9d93d312-f9af-7e47-6475-6e2164756e21";
+var BUNDLE_DEBUG_ID_PLACEHOLDER = "41cac967-78f1-f75a-6475-6e2164756e21";
 
 // src/telemetry/telemetry.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
@@ -60326,11 +60326,11 @@ dosu skill install | remove | update
 dosu telemetry status [--json]
 dosu telemetry enable | disable | reset
 dosu insights
-dosu upgrade
+dosu upgrade [--auto on|off]
 dosu logs [--tail [n]] [--clear]
 \`\`\`
 
-\`deployments\` selects the MCP deployment stored in local config; it is distinct from \`agents\`. \`insights\` opens an interactive visual report. \`logs --clear\` deletes the CLI log file.
+\`deployments\` selects the MCP deployment stored in local config; it is distinct from \`agents\`. \`insights\` opens an interactive visual report. \`logs --clear\` deletes the CLI log file. The CLI updates itself in the background by default; a \`[dosu:update] Installing ...\` notice on stderr needs no action. \`upgrade --auto off\` turns that off.
 
 ## Codebase audit
 
@@ -61641,283 +61641,6 @@ var init_topics = __esm(() => {
   import_picocolors29 = __toESM(require_picocolors(), 1);
 });
 
-// src/commands/upgrade.ts
-import { spawnSync } from "node:child_process";
-import { realpathSync as realpathSync2 } from "node:fs";
-import { homedir as homedir9 } from "node:os";
-import { posix, win32 as win322 } from "node:path";
-function isAbsoluteCommandProcessor(value) {
-  return Boolean(value && win322.isAbsolute(value) && win322.basename(value).toLowerCase() === "cmd.exe");
-}
-function windowsCommandProcessor(env = process.env) {
-  if (isAbsoluteCommandProcessor(env.ComSpec))
-    return env.ComSpec;
-  const systemRoot = env.SystemRoot && win322.isAbsolute(env.SystemRoot) ? env.SystemRoot : "C:\\Windows";
-  return win322.join(systemRoot, "System32", "cmd.exe");
-}
-function safePackageManagerEnv(env) {
-  return {
-    ...env,
-    COREPACK_ENABLE_NETWORK: "0",
-    COREPACK_ENABLE_PROJECT_SPEC: "0",
-    YARN_IGNORE_PATH: "1"
-  };
-}
-function buildPackageManagerInvocation(manager, action, platform = process.platform, comSpec, env = process.env) {
-  const args = action === "locate" ? PACKAGE_MANAGERS[manager].locateArgs : PACKAGE_MANAGERS[manager].installArgs;
-  const safeEnv = safePackageManagerEnv(env);
-  if (platform === "win32") {
-    return {
-      command: isAbsoluteCommandProcessor(comSpec) ? comSpec : windowsCommandProcessor(env),
-      args: ["/d", "/s", "/c", [manager, ...args].join(" ")],
-      env: { ...safeEnv, NoDefaultCurrentDirectoryInExePath: "1" }
-    };
-  }
-  return { command: manager, args: [...args], env: safeEnv };
-}
-function packageRoots(manager, platform, comSpec, env, cwd) {
-  const invocation = buildPackageManagerInvocation(manager, "locate", platform, comSpec, env);
-  const result = spawnSync(invocation.command, invocation.args, {
-    cwd,
-    encoding: "utf8",
-    env: invocation.env,
-    shell: false,
-    stdio: ["ignore", "pipe", "ignore"],
-    timeout: PROBE_TIMEOUT_MS
-  });
-  if (result.status !== 0 || typeof result.stdout !== "string")
-    return [];
-  const path = platform === "win32" ? win322 : posix;
-  const lines = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => path.isAbsolute(line));
-  if (manager === "pnpm") {
-    return lines.filter((line) => path.basename(line) === "cli" && path.basename(path.dirname(line)) === "@dosu" && path.basename(path.dirname(path.dirname(line))) === "node_modules");
-  }
-  if (lines.length !== 1)
-    return [];
-  return [
-    manager === "npm" ? path.join(lines[0], "@dosu", "cli") : path.join(lines[0], "node_modules", "@dosu", "cli")
-  ];
-}
-function owningPackageManager(entrypoint, platform, comSpec, env = process.env, cwd = homedir9()) {
-  const path = platform === "win32" ? win322 : posix;
-  if (!entrypoint || !path.isAbsolute(entrypoint))
-    return null;
-  let realEntrypoint;
-  try {
-    realEntrypoint = realpathSync2(entrypoint);
-  } catch {
-    return null;
-  }
-  const owners = Object.keys(PACKAGE_MANAGERS).filter((manager) => packageRoots(manager, platform, comSpec, env, cwd).some((root) => {
-    try {
-      const relative = path.relative(realpathSync2(root), realEntrypoint);
-      return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-    } catch {
-      return false;
-    }
-  }));
-  return owners.length === 1 ? owners[0] : null;
-}
-function upgradePlan(channel, manager, platform, comSpec, env = process.env) {
-  if (channel === "homebrew") {
-    return {
-      label: "Homebrew",
-      command: "brew",
-      args: ["upgrade", "dosu-ai/dosu/dosu"],
-      manualCommand: BREW_MANUAL_COMMAND
-    };
-  }
-  if (channel === "npm" && manager) {
-    const invocation = buildPackageManagerInvocation(manager, "install", platform, comSpec, env);
-    return {
-      label: PACKAGE_MANAGERS[manager].label,
-      ...invocation,
-      manualCommand: [manager, ...PACKAGE_MANAGERS[manager].installArgs].join(" ")
-    };
-  }
-  return null;
-}
-function printNonGlobalPackageGuidance() {
-  console.log("This Dosu copy is not a uniquely identified global package installation, so it was not changed.");
-  console.log(`
-Run the latest version without installing:
-  ${NPX_COMMAND}`);
-  console.log(`
-Or install Dosu globally with your package manager:`);
-  for (const manager of Object.keys(PACKAGE_MANAGERS)) {
-    console.log(`  ${manager} ${PACKAGE_MANAGERS[manager].installArgs.join(" ")}`);
-  }
-}
-function runUpgrade(channel = INSTALL_CHANNEL, options = {}) {
-  const platform = options.platform ?? process.platform;
-  const env = options.env ?? process.env;
-  const cwd = options.cwd ?? homedir9();
-  let manager = null;
-  if (channel === "npm") {
-    if (isNpxInvocation(channel, env)) {
-      printNonGlobalPackageGuidance();
-      return 1;
-    }
-    manager = owningPackageManager(options.entrypoint ?? process.argv[1], platform, options.comSpec, env, cwd);
-    if (!manager) {
-      if (env.DOSU_DEV === "true") {
-        console.log("DOSU_DEV=true and this copy is not a global package: skipping the package install.");
-        return 0;
-      }
-      printNonGlobalPackageGuidance();
-      return 1;
-    }
-  }
-  const plan = upgradePlan(channel, manager, platform, options.comSpec, env);
-  if (!plan) {
-    console.log("Automatic upgrades are not available for this installation yet.");
-    console.log(`Download the latest release:
-  ${RELEASES_URL}`);
-    return 1;
-  }
-  console.log(`Updating Dosu with ${plan.label}...`);
-  console.log(`  ${plan.manualCommand}
-`);
-  const result = spawnSync(plan.command, plan.args, {
-    ...channel === "npm" ? { cwd } : {},
-    ...plan.env ? { env: plan.env } : {},
-    shell: false,
-    stdio: "inherit"
-  });
-  if (result.error || result.status !== 0) {
-    console.error(`
-Could not update Dosu automatically.`);
-    console.error(`Run manually:
-  ${plan.manualCommand}`);
-    return result.status && result.status > 0 ? result.status : 1;
-  }
-  console.log(import_picocolors30.default.green(`
-✓ Update command completed.`));
-  console.log('Run "dosu --version" to verify.');
-  return 0;
-}
-function postUpgradeArgs(interactive) {
-  return interactive ? ["setup"] : ["mcp", "refresh"];
-}
-function newBinaryInvocation(channel, args, entrypoint = process.argv[1], execPath = process.execPath) {
-  if (channel === "npm") {
-    return entrypoint ? { command: execPath, args: [entrypoint, ...args] } : null;
-  }
-  if (channel === "homebrew") {
-    return { command: "dosu", args };
-  }
-  return null;
-}
-function isInteractiveTerminal() {
-  return process.stdin.isTTY === true && process.stdout.isTTY === true;
-}
-function setupAgentsWithNewBinary(channel, interactive, options) {
-  const invocation = newBinaryInvocation(channel, postUpgradeArgs(interactive), options.entrypoint ?? process.argv[1]);
-  if (!invocation) {
-    console.error(SETUP_FALLBACK);
-    return;
-  }
-  console.log(interactive ? `
-Running setup with the new version to update your AI agents...
-` : `
-Refreshing agent MCP configs with the new version...`);
-  const result = spawnSync(invocation.command, invocation.args, {
-    cwd: options.cwd ?? homedir9(),
-    shell: false,
-    stdio: "inherit"
-  });
-  if (result.error || result.status !== 0) {
-    console.error(SETUP_FALLBACK);
-  }
-}
-async function completeUpgrade(channel = INSTALL_CHANNEL, options = {}) {
-  const status = runUpgrade(channel, options);
-  if (status !== 0)
-    return status;
-  const interactive = options.interactive ?? isInteractiveTerminal();
-  if (!interactive) {
-    console.log("Updating Dosu skills...");
-    try {
-      const result = await installSkill();
-      if (result.success) {
-        console.log(import_picocolors30.default.green("✓ Skills updated."));
-      } else {
-        console.error('Skills could not be refreshed. Run "dosu skill update" to retry.');
-      }
-    } catch {
-      console.error('Skills could not be refreshed. Run "dosu skill update" to retry.');
-    }
-  }
-  setupAgentsWithNewBinary(channel, interactive, options);
-  return 0;
-}
-function upgradeCommand() {
-  return new Command("upgrade").description("Update Dosu to the latest version, then re-run setup to update your AI agents").action(async () => {
-    const status = await completeUpgrade();
-    if (status !== 0)
-      process.exitCode = status;
-  });
-}
-var import_picocolors30, PACKAGE_NAME = "@dosu/cli", LATEST_PACKAGE, BREW_MANUAL_COMMAND = "brew upgrade dosu-ai/dosu/dosu", NPX_COMMAND = "npx -y @dosu/cli@latest", PROBE_TIMEOUT_MS = 5000, RELEASES_URL = "https://github.com/dosu-ai/dosu-cli/releases/latest", PACKAGE_MANAGERS, SETUP_FALLBACK = 'Run "dosu setup" to finish updating your AI agents.';
-var init_upgrade = __esm(() => {
-  init_commander();
-  init_skill();
-  import_picocolors30 = __toESM(require_picocolors(), 1);
-  LATEST_PACKAGE = `${PACKAGE_NAME}@latest`;
-  PACKAGE_MANAGERS = {
-    npm: {
-      label: "npm",
-      locateArgs: ["root", "-g"],
-      installArgs: ["install", "-g", LATEST_PACKAGE]
-    },
-    pnpm: {
-      label: "pnpm",
-      locateArgs: ["list", "-g", "--depth=0", "--parseable", PACKAGE_NAME],
-      installArgs: ["add", "-g", LATEST_PACKAGE]
-    },
-    yarn: {
-      label: "Yarn Classic",
-      locateArgs: ["--silent", "global", "dir"],
-      installArgs: ["global", "add", LATEST_PACKAGE]
-    }
-  };
-});
-
-// src/debug/follow.ts
-import { closeSync as closeSync6, openSync as openSync6, readSync as readSync5, statSync as statSync8 } from "node:fs";
-function createLogFollower(path, emit) {
-  const sizeOf = () => {
-    try {
-      return statSync8(path).size;
-    } catch {
-      return 0;
-    }
-  };
-  let offset = sizeOf();
-  return {
-    poll() {
-      const size = sizeOf();
-      if (size < offset)
-        offset = 0;
-      if (size === offset)
-        return;
-      try {
-        const fd = openSync6(path, "r");
-        try {
-          const buf = Buffer.alloc(size - offset);
-          const read = readSync5(fd, buf, 0, buf.length, offset);
-          offset += read;
-          if (read > 0)
-            emit(buf.toString("utf-8", 0, read));
-        } finally {
-          closeSync6(fd);
-        }
-      } catch {}
-    }
-  };
-}
-var init_follow = () => {};
-
 // src/mcp/providers/base.ts
 function createJSONProvider(opts) {
   const buildServer = opts.buildServer ?? defaultBuildServer;
@@ -62449,15 +62172,15 @@ var init_vscode = __esm(() => {
 });
 
 // src/mcp/providers/windsurf.ts
-import { homedir as homedir10 } from "node:os";
+import { homedir as homedir9 } from "node:os";
 import { join as join36 } from "node:path";
 var WindsurfProvider = () => createJSONProvider({
   providerName: "Windsurf",
   providerID: "windsurf",
   local: false,
   priorityValue: 9,
-  paths: [join36(homedir10(), ".codeium", "windsurf")],
-  globalPath: join36(homedir10(), ".codeium", "windsurf", "mcp_config.json"),
+  paths: [join36(homedir9(), ".codeium", "windsurf")],
+  globalPath: join36(homedir9(), ".codeium", "windsurf", "mcp_config.json"),
   topKey: "mcpServers"
 });
 var init_windsurf = __esm(() => {
@@ -62466,14 +62189,14 @@ var init_windsurf = __esm(() => {
 
 // src/mcp/providers/zed.ts
 import { rmSync as rmSync6 } from "node:fs";
-import { homedir as homedir11, platform as platform3 } from "node:os";
+import { homedir as homedir10, platform as platform3 } from "node:os";
 import { join as join37 } from "node:path";
 function zedConfigDir() {
   const os = platform3();
   if (os === "win32")
     return join37(appSupportDir(), "Zed");
   if (os === "darwin")
-    return join37(homedir11(), ".config", "zed");
+    return join37(homedir10(), ".config", "zed");
   return join37(appSupportDir(), "zed");
 }
 function zedDataDir() {
@@ -62482,7 +62205,7 @@ function zedDataDir() {
     return join37(appSupportDir(), "Zed");
   if (os === "win32")
     return join37(process.env.LOCALAPPDATA ?? "", "Zed");
-  return join37(process.env.XDG_DATA_HOME ?? join37(homedir11(), ".local", "share"), "zed");
+  return join37(process.env.XDG_DATA_HOME ?? join37(homedir10(), ".local", "share"), "zed");
 }
 function legacyDarwinSettingsPath() {
   return platform3() === "darwin" ? join37(appSupportDir(), "Zed", "settings.json") : null;
@@ -62618,10 +62341,204 @@ var init_refresh = __esm(() => {
   init_providers();
 });
 
-// src/version/update-check.ts
-import { existsSync as existsSync23, mkdirSync as mkdirSync13, readFileSync as readFileSync22, writeFileSync as writeFileSync14 } from "node:fs";
+// src/version/auto-update.ts
+import { spawn as spawn3 } from "node:child_process";
+import {
+  closeSync as closeSync6,
+  existsSync as existsSync23,
+  mkdirSync as mkdirSync13,
+  openSync as openSync6,
+  readFileSync as readFileSync22,
+  rmSync as rmSync7,
+  statSync as statSync8,
+  writeFileSync as writeFileSync14,
+  writeSync
+} from "node:fs";
+import { homedir as homedir11 } from "node:os";
 import { join as join38 } from "node:path";
+function statePath() {
+  return join38(getConfigDir(), STATE_FILENAME2);
+}
+function lockPath2() {
+  return join38(getConfigDir(), LOCK_FILENAME2);
+}
 function isValidVersion(value) {
+  return typeof value === "string" && VERSION_PATTERN.test(value);
+}
+function readState() {
+  try {
+    const raw = JSON.parse(readFileSync22(statePath(), "utf-8"));
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+      return {};
+    const data = raw;
+    const state = {};
+    if (data.disabled === true)
+      state.disabled = true;
+    const last = data.lastAttempt;
+    if (last && isValidVersion(last.version) && typeof last.ok === "boolean" && typeof last.finishedAt === "number") {
+      state.lastAttempt = { version: last.version, ok: last.ok, finishedAt: last.finishedAt };
+    }
+    return state;
+  } catch {
+    return {};
+  }
+}
+function writeState(state) {
+  try {
+    const dir = getConfigDir();
+    if (!existsSync23(dir))
+      mkdirSync13(dir, { recursive: true, mode: 448 });
+    writeFileSync14(statePath(), `${JSON.stringify(state, null, 2)}
+`, { mode: 384 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isEnabledFlag(value) {
+  if (value === undefined)
+    return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized !== "" && !["0", "false", "no", "off"].includes(normalized);
+}
+function autoUpdateDisabledReason(env = process.env) {
+  if (isEnabledFlag(env[AUTO_UPDATE_ENV]))
+    return "env";
+  if (readState().disabled)
+    return "settings";
+  return;
+}
+function setAutoUpdateEnabled(enabled) {
+  const state = readState();
+  if (enabled)
+    delete state.disabled;
+  else
+    state.disabled = true;
+  return writeState(state);
+}
+function canAutoUpdate(channel, env) {
+  if (env.NODE_ENV === "test" || env.CI || env.DOSU_DEV === "true")
+    return false;
+  if (!SUPPORTED_CHANNELS.has(channel) || isNpxInvocation(channel, env))
+    return false;
+  return autoUpdateDisabledReason(env) === undefined;
+}
+function backgroundInvocation(channel, entrypoint = process.argv[1], execPath = process.execPath) {
+  const args = ["upgrade", "--background"];
+  if (channel === "npm") {
+    return entrypoint ? { command: execPath, args: [entrypoint, ...args] } : null;
+  }
+  if (channel === "homebrew")
+    return { command: execPath, args };
+  return null;
+}
+function lockIsFresh(now) {
+  try {
+    return now - statSync8(lockPath2()).mtimeMs < LOCK_STALE_MS;
+  } catch {
+    return false;
+  }
+}
+function claimLock(version, now) {
+  try {
+    mkdirSync13(getConfigDir(), { recursive: true, mode: 448 });
+    if (!lockIsFresh(now))
+      rmSync7(lockPath2(), { force: true });
+    const fd = openSync6(lockPath2(), "wx", 384);
+    try {
+      writeSync(fd, version);
+    } finally {
+      closeSync6(fd);
+    }
+    return "claimed";
+  } catch (err) {
+    return err.code === "EEXIST" ? "held" : "failed";
+  }
+}
+function releaseLock() {
+  try {
+    rmSync7(lockPath2(), { force: true });
+  } catch {}
+}
+function readLockVersion() {
+  try {
+    const version = readFileSync22(lockPath2(), "utf-8").trim();
+    return isValidVersion(version) ? version : undefined;
+  } catch {
+    return;
+  }
+}
+function startAutoUpdate(version, options = {}) {
+  const channel = options.channel ?? INSTALL_CHANNEL;
+  const env = options.env ?? process.env;
+  const now = options.now ?? Date.now();
+  try {
+    if (!isValidVersion(version) || !canAutoUpdate(channel, env))
+      return "unavailable";
+    if (lockIsFresh(now))
+      return "in_progress";
+    const last = readState().lastAttempt;
+    if (last?.version === version && now - last.finishedAt < RETRY_INTERVAL_MS) {
+      return "unavailable";
+    }
+    const invocation = backgroundInvocation(channel, options.entrypoint, options.execPath);
+    if (!invocation)
+      return "unavailable";
+    const claim = claimLock(version, now);
+    if (claim !== "claimed")
+      return claim === "held" ? "in_progress" : "unavailable";
+    try {
+      const child = spawn3(invocation.command, invocation.args, {
+        cwd: homedir11(),
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env: { ...env, DOSU_TELEMETRY_DISABLED: "1" }
+      });
+      child.on("error", releaseLock);
+      child.unref();
+    } catch (err) {
+      releaseLock();
+      throw err;
+    }
+    logger.info("auto-update", `Started background update to ${version}`);
+    return "started";
+  } catch (err) {
+    logger.error("auto-update", `Could not start background update: ${err}`);
+    return "unavailable";
+  }
+}
+function runBackgroundUpgrade(upgrade, now = Date.now) {
+  const version = readLockVersion();
+  let status = 1;
+  try {
+    status = upgrade();
+  } catch (err) {
+    logger.error("auto-update", `Background update threw: ${err}`);
+  }
+  if (version) {
+    const state = readState();
+    state.lastAttempt = { version, ok: status === 0, finishedAt: now() };
+    writeState(state);
+  }
+  logger.info("auto-update", `Background update ${status === 0 ? "finished" : "failed"}`);
+  releaseLock();
+  return status;
+}
+var STATE_FILENAME2 = "auto-update.json", LOCK_FILENAME2 = "auto-update.lock", LOCK_STALE_MS, RETRY_INTERVAL_MS, SUPPORTED_CHANNELS, VERSION_PATTERN, AUTO_UPDATE_ENV = "DOSU_DISABLE_AUTOUPDATE";
+var init_auto_update = __esm(() => {
+  init_config();
+  init_logger();
+  LOCK_STALE_MS = 15 * 60 * 1000;
+  RETRY_INTERVAL_MS = 6 * 60 * 60 * 1000;
+  SUPPORTED_CHANNELS = new Set(["npm", "homebrew"]);
+  VERSION_PATTERN = /^[0-9A-Za-z.+-]{1,64}$/;
+});
+
+// src/version/update-check.ts
+import { existsSync as existsSync24, mkdirSync as mkdirSync14, readFileSync as readFileSync23, writeFileSync as writeFileSync15 } from "node:fs";
+import { join as join39 } from "node:path";
+function isValidVersion2(value) {
   return typeof value === "string" && SEMVER_PATTERN.test(value);
 }
 function stripPrerelease(version) {
@@ -62642,15 +62559,15 @@ function isNewerVersion(latest, current) {
   return false;
 }
 function getCachePath2() {
-  return join38(getConfigDir(), CACHE_FILENAME3);
+  return join39(getConfigDir(), CACHE_FILENAME3);
 }
 function readCache() {
   try {
     const path = getCachePath2();
-    if (!existsSync23(path))
+    if (!existsSync24(path))
       return null;
-    const data = JSON.parse(readFileSync22(path, "utf-8"));
-    if (typeof data.lastCheck === "number" && isValidVersion(data.latestVersion)) {
+    const data = JSON.parse(readFileSync23(path, "utf-8"));
+    if (typeof data.lastCheck === "number" && isValidVersion2(data.latestVersion)) {
       return data;
     }
     return null;
@@ -62661,10 +62578,10 @@ function readCache() {
 function writeCache(cache) {
   try {
     const dir = getConfigDir();
-    if (!existsSync23(dir)) {
-      mkdirSync13(dir, { recursive: true, mode: 448 });
+    if (!existsSync24(dir)) {
+      mkdirSync14(dir, { recursive: true, mode: 448 });
     }
-    writeFileSync14(getCachePath2(), JSON.stringify(cache), { mode: 384 });
+    writeFileSync15(getCachePath2(), JSON.stringify(cache), { mode: 384 });
   } catch {}
 }
 async function fetchLatestVersion() {
@@ -62676,7 +62593,7 @@ async function fetchLatestVersion() {
       return null;
     const data = await resp.json();
     const latest = data.latest;
-    return isValidVersion(latest) ? latest : null;
+    return isValidVersion2(latest) ? latest : null;
   } catch {
     return null;
   } finally {
@@ -62692,34 +62609,47 @@ function buildUpdateHint(channel, npx = false) {
 function styleHint(hint) {
   const match = hint.match(/^(.*)("[^"]+")(.*)$/);
   if (!match)
-    return import_picocolors31.default.dim(hint);
+    return import_picocolors30.default.dim(hint);
   const [, before, command, after] = match;
-  return [before && import_picocolors31.default.dim(before), import_picocolors31.default.cyan(command), after && import_picocolors31.default.dim(after)].filter(Boolean).join("");
+  return [before && import_picocolors30.default.dim(before), import_picocolors30.default.cyan(command), after && import_picocolors30.default.dim(after)].filter(Boolean).join("");
+}
+function framedNotice(content, width) {
+  const innerWidth = Math.max(...content.map(visibleWidth2)) + BOX_PADDING * 2;
+  const framed = (line) => {
+    const pad = innerWidth - visibleWidth2(line);
+    const left = Math.floor(pad / 2);
+    return `${import_picocolors30.default.yellow("│")}${" ".repeat(left)}${line}${" ".repeat(pad - left)}${import_picocolors30.default.yellow("│")}`;
+  };
+  const box = [
+    import_picocolors30.default.yellow(`╭${"─".repeat(innerWidth)}╮`),
+    framed(""),
+    ...content.map(framed),
+    framed(""),
+    import_picocolors30.default.yellow(`╰${"─".repeat(innerWidth)}╯`)
+  ];
+  return `
+${centerBlock(box, width).join(`
+`)}
+`;
+}
+function versionArrow(current, latest) {
+  return `${import_picocolors30.default.dim(current)} ${import_picocolors30.default.dim("→")} ${import_picocolors30.default.bold(brand(latest))}`;
+}
+function buildAutoUpdateNotice(current, latest, interactive, width = process.stderr.columns ?? 80) {
+  if (interactive) {
+    return framedNotice([
+      `Updating Dosu: ${versionArrow(current, latest)}`,
+      import_picocolors30.default.dim("Installing in the background; your next command uses it")
+    ], width);
+  }
+  return `
+[dosu:update] Installing Dosu ${latest} in the background (running ${current}). ` + `The next Dosu command uses it; no action needed.
+`;
 }
 function buildUpdateNotice(current, latest, channel, interactive, npx = false, width = process.stderr.columns ?? 80) {
   const hint = buildUpdateHint(channel, npx);
   if (interactive) {
-    const content = [
-      `Update available: ${import_picocolors31.default.dim(current)} ${import_picocolors31.default.dim("→")} ${import_picocolors31.default.bold(brand(latest))}`,
-      styleHint(hint)
-    ];
-    const innerWidth = Math.max(...content.map(visibleWidth2)) + BOX_PADDING * 2;
-    const framed = (line) => {
-      const pad = innerWidth - visibleWidth2(line);
-      const left = Math.floor(pad / 2);
-      return `${import_picocolors31.default.yellow("│")}${" ".repeat(left)}${line}${" ".repeat(pad - left)}${import_picocolors31.default.yellow("│")}`;
-    };
-    const box = [
-      import_picocolors31.default.yellow(`╭${"─".repeat(innerWidth)}╮`),
-      framed(""),
-      ...content.map(framed),
-      framed(""),
-      import_picocolors31.default.yellow(`╰${"─".repeat(innerWidth)}╯`)
-    ];
-    return `
-${centerBlock(box, width).join(`
-`)}
-`;
+    return framedNotice([`Update available: ${versionArrow(current, latest)}`, styleHint(hint)], width);
   }
   const agentAction = hint[0].toLowerCase() + hint.slice(1);
   const verifyCommand = npx ? "npx -y @dosu/cli@latest --version" : "dosu --version";
@@ -62732,8 +62662,12 @@ function getAvailableUpdate() {
   const cache = readCache();
   return cache && isNewerVersion(cache.latestVersion, VERSION) ? cache.latestVersion : null;
 }
-function displayNotice(current, latest) {
-  console.error(buildUpdateNotice(current, latest, INSTALL_CHANNEL, process.stderr.isTTY === true, isNpxInvocation()));
+function handleNewerVersion(latest, notify) {
+  const autoUpdate = startAutoUpdate(latest);
+  if (!notify)
+    return;
+  const interactive = process.stderr.isTTY === true;
+  console.error(autoUpdate === "unavailable" ? buildUpdateNotice(VERSION, latest, INSTALL_CHANNEL, interactive, isNpxInvocation()) : buildAutoUpdateNotice(VERSION, latest, interactive));
 }
 async function checkForUpdates(options = {}) {
   const notify = options.notify ?? true;
@@ -62741,8 +62675,8 @@ async function checkForUpdates(options = {}) {
     const cache = readCache();
     const isStale = !cache || Date.now() - cache.lastCheck > CHECK_INTERVAL_MS2;
     if (!isStale) {
-      if (notify && isNewerVersion(cache.latestVersion, VERSION)) {
-        displayNotice(VERSION, cache.latestVersion);
+      if (isNewerVersion(cache.latestVersion, VERSION)) {
+        handleNewerVersion(cache.latestVersion, notify);
       }
       return;
     }
@@ -62755,27 +62689,28 @@ async function checkForUpdates(options = {}) {
     if (latest) {
       logger.debug("update-check", `Cached latest version: ${latest}`);
     }
-    if (notify && isNewerVersion(latestKnownVersion, VERSION)) {
-      displayNotice(VERSION, latestKnownVersion);
+    if (isNewerVersion(latestKnownVersion, VERSION)) {
+      handleNewerVersion(latestKnownVersion, notify);
     }
   } catch (err) {
     logger.error("update-check", `Update check failed: ${err}`);
   }
 }
-var import_picocolors31, CACHE_FILENAME3 = "update-check.json", CHECK_INTERVAL_MS2, FETCH_TIMEOUT_MS2 = 1000, REGISTRY_URL = "https://registry.npmjs.org/-/package/@dosu/cli/dist-tags", SEMVER_PATTERN, BOX_PADDING = 3;
+var import_picocolors30, CACHE_FILENAME3 = "update-check.json", CHECK_INTERVAL_MS2, FETCH_TIMEOUT_MS2 = 1000, REGISTRY_URL = "https://registry.npmjs.org/-/package/@dosu/cli/dist-tags", SEMVER_PATTERN, BOX_PADDING = 3;
 var init_update_check = __esm(() => {
   init_config();
   init_logger();
   init_styles();
   init_layout();
-  import_picocolors31 = __toESM(require_picocolors(), 1);
+  init_auto_update();
+  import_picocolors30 = __toESM(require_picocolors(), 1);
   CHECK_INTERVAL_MS2 = 6 * 60 * 60 * 1000;
   SEMVER_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 });
 
 // src/version/mcp-refresh-check.ts
-import { existsSync as existsSync24, mkdirSync as mkdirSync14, readFileSync as readFileSync23, writeFileSync as writeFileSync15 } from "node:fs";
-import { join as join39 } from "node:path";
+import { existsSync as existsSync25, mkdirSync as mkdirSync15, readFileSync as readFileSync24, writeFileSync as writeFileSync16 } from "node:fs";
+import { join as join40 } from "node:path";
 function needsMcpRefresh(previous, current) {
   if (previous === null)
     return true;
@@ -62785,14 +62720,14 @@ function needsMcpRefresh(previous, current) {
   return MCP_FORMAT_CHANGES.some((change) => isNewerVersion(change, older) && !isNewerVersion(change, newer));
 }
 function getCachePath3() {
-  return join39(getConfigDir(), CACHE_FILENAME4);
+  return join40(getConfigDir(), CACHE_FILENAME4);
 }
 function readMcpRefreshCache() {
   try {
     const path = getCachePath3();
-    if (!existsSync24(path))
+    if (!existsSync25(path))
       return null;
-    const data = JSON.parse(readFileSync23(path, "utf-8"));
+    const data = JSON.parse(readFileSync24(path, "utf-8"));
     if (typeof data?.version === "string")
       return { version: data.version };
     return null;
@@ -62803,10 +62738,10 @@ function readMcpRefreshCache() {
 function writeMcpRefreshCache(cache) {
   try {
     const dir = getConfigDir();
-    if (!existsSync24(dir)) {
-      mkdirSync14(dir, { recursive: true, mode: 448 });
+    if (!existsSync25(dir)) {
+      mkdirSync15(dir, { recursive: true, mode: 448 });
     }
-    writeFileSync15(getCachePath3(), JSON.stringify(cache), { mode: 384 });
+    writeFileSync16(getCachePath3(), JSON.stringify(cache), { mode: 384 });
   } catch {}
 }
 function canRefreshMcp(cfg) {
@@ -62815,10 +62750,10 @@ function canRefreshMcp(cfg) {
     return false;
   return cfg.mode === MODE_OSS || Boolean(target.deployment_id);
 }
-function displayNotice2(names) {
+function displayNotice(names) {
   console.error(`
-${import_picocolors32.default.green(`✓ Dosu ${VERSION}: refreshed MCP config for ${names.join(", ")}`)}
-` + `${import_picocolors32.default.dim(`  Run ${import_picocolors32.default.cyan('"dosu setup"')} to also update hooks and rules, then restart your AI agents.`)}
+${import_picocolors31.default.green(`✓ Dosu ${VERSION}: refreshed MCP config for ${names.join(", ")}`)}
+` + `${import_picocolors31.default.dim(`  Run ${import_picocolors31.default.cyan('"dosu setup"')} to also update hooks and rules, then restart your AI agents.`)}
 `);
 }
 function checkForMcpRefresh(options = {}) {
@@ -62840,27 +62775,27 @@ function checkForMcpRefresh(options = {}) {
     writeMcpRefreshCache({ version: VERSION });
     logger.info("mcp-refresh", `Version ${VERSION}: refreshed ${result.updated.length}, failed ${result.failed.length}`);
     if (notify && result.updated.length > 0) {
-      displayNotice2(result.updated.map((provider) => provider.name()));
+      displayNotice(result.updated.map((provider) => provider.name()));
     }
   } catch (err) {
     logger.error("mcp-refresh", `MCP refresh check failed: ${err}`);
   }
 }
-var import_picocolors32, CACHE_FILENAME4 = "mcp-refresh.json", MCP_FORMAT_CHANGES;
+var import_picocolors31, CACHE_FILENAME4 = "mcp-refresh.json", MCP_FORMAT_CHANGES;
 var init_mcp_refresh_check = __esm(() => {
   init_config();
   init_logger();
   init_refresh();
   init_update_check();
-  import_picocolors32 = __toESM(require_picocolors(), 1);
+  import_picocolors31 = __toESM(require_picocolors(), 1);
   MCP_FORMAT_CHANGES = ["0.53.0"];
 });
 
 // src/version/skill-update-check.ts
-function displayNotice3() {
+function displayNotice2() {
   console.error(`
-${import_picocolors33.default.green(`✓ Dosu ${VERSION}: refreshed the bundled agent skills`)}
-` + `${import_picocolors33.default.dim("  Restart your AI agents to pick up the new skill content.")}
+${import_picocolors32.default.green(`✓ Dosu ${VERSION}: refreshed the bundled agent skills`)}
+` + `${import_picocolors32.default.dim("  Restart your AI agents to pick up the new skill content.")}
 `);
 }
 function checkForSkillUpdates(options = {}) {
@@ -62876,294 +62811,16 @@ function checkForSkillUpdates(options = {}) {
     }
     logger.info("skill-update-check", `Refreshed skills from ${state.version} to ${VERSION}`);
     if (notify && result.version)
-      displayNotice3();
+      displayNotice2();
   } catch (err) {
     logger.error("skill-update-check", `Skill update check failed: ${err}`);
   }
 }
-var import_picocolors33;
+var import_picocolors32;
 var init_skill_update_check = __esm(() => {
   init_skill();
   init_logger();
-  import_picocolors33 = __toESM(require_picocolors(), 1);
-});
-
-// src/rules/installer.ts
-import { existsSync as existsSync25, mkdirSync as mkdirSync15, readFileSync as readFileSync24, unlinkSync as unlinkSync5, writeFileSync as writeFileSync16 } from "node:fs";
-import { homedir as homedir12 } from "node:os";
-import { dirname as dirname12, join as join40 } from "node:path";
-function claudeConfigDir4() {
-  return process.env.CLAUDE_CONFIG_DIR || join40(homedir12(), ".claude");
-}
-function codexHome4() {
-  return process.env.CODEX_HOME || join40(homedir12(), ".codex");
-}
-function isRuleAgent(agent) {
-  return Object.hasOwn(RULE_TARGETS, agent);
-}
-function rulePathForAgent(agent) {
-  return isRuleAgent(agent) ? RULE_TARGETS[agent].path() : null;
-}
-function normalizeRule(content) {
-  return `${content.trim()}
-`;
-}
-async function fetchDosuRule(fetchImpl = globalThis.fetch) {
-  for (const url of DOSU_RULE_URLS) {
-    try {
-      const response = await fetchImpl(url);
-      if (!response.ok)
-        continue;
-      const content = await response.text();
-      if (content.trim())
-        return normalizeRule(content);
-    } catch {}
-  }
-  return normalizeRule(FALLBACK_DOSU_RULE);
-}
-function ensureParent(path) {
-  mkdirSync15(dirname12(path), { recursive: true });
-}
-function writeIfChanged(path, content) {
-  if (!existsSync25(path)) {
-    ensureParent(path);
-    writeFileSync16(path, content, "utf-8");
-    return "created";
-  }
-  if (readFileSync24(path, "utf-8") === content)
-    return "unchanged";
-  writeFileSync16(path, content, "utf-8");
-  return "updated";
-}
-function findSection(content) {
-  const startMatch = content.match(DOSU_RULE_SECTION_START_RE);
-  const start = startMatch?.index ?? -1;
-  const end = content.indexOf(DOSU_RULE_SECTION_END, Math.max(start, 0));
-  if (start === -1 && end === -1)
-    return null;
-  if (start === -1 || end < start) {
-    throw new Error("Dosu rule markers are incomplete; refusing to overwrite the instruction file");
-  }
-  return { start, end };
-}
-function lineEndingFor(content) {
-  return content.includes(`\r
-`) ? `\r
-` : `
-`;
-}
-function buildSection(content, lineEnding = `
-`) {
-  const body = content.trimEnd().replace(/\r?\n/g, lineEnding);
-  return `${DOSU_RULE_SECTION_START}${lineEnding}${body}${lineEnding}${DOSU_RULE_SECTION_END}`;
-}
-function upsertSection(path, content) {
-  if (!existsSync25(path)) {
-    const section = buildSection(content);
-    ensureParent(path);
-    writeFileSync16(path, `${section}
-`, "utf-8");
-    return "created";
-  }
-  const existing = readFileSync24(path, "utf-8");
-  const lineEnding = lineEndingFor(existing);
-  const section = buildSection(content, lineEnding);
-  const location = findSection(existing);
-  let next;
-  if (location) {
-    next = existing.slice(0, location.start) + section + existing.slice(location.end + DOSU_RULE_SECTION_END.length);
-  } else {
-    const separator = existing.length > 0 && !existing.endsWith(lineEnding) ? `${lineEnding}${lineEnding}` : existing.length > 0 ? lineEnding : "";
-    next = `${existing}${separator}${section}${lineEnding}`;
-  }
-  if (next === existing)
-    return "unchanged";
-  writeFileSync16(path, next, "utf-8");
-  return "updated";
-}
-function installRuleForAgent(agent, content) {
-  if (!isRuleAgent(agent))
-    return null;
-  const target = RULE_TARGETS[agent];
-  const path = target.path();
-  const normalized = normalizeRule(content);
-  const action = target.kind === "file" ? writeIfChanged(path, target.cursorFrontmatter ? `${CURSOR_FRONTMATTER}${normalized}` : normalized) : upsertSection(path, normalized);
-  return { agent, path, action };
-}
-function removeRuleForAgent(agent) {
-  if (!isRuleAgent(agent))
-    return null;
-  const target = RULE_TARGETS[agent];
-  const path = target.path();
-  if (!existsSync25(path))
-    return { agent, path, action: "not_found" };
-  if (target.kind === "file") {
-    unlinkSync5(path);
-    return { agent, path, action: "removed" };
-  }
-  const existing = readFileSync24(path, "utf-8");
-  const lineEnding = lineEndingFor(existing);
-  const location = findSection(existing);
-  if (!location)
-    return { agent, path, action: "not_found" };
-  const next = (existing.slice(0, location.start) + existing.slice(location.end + DOSU_RULE_SECTION_END.length)).replace(/(?:\r?\n){3,}/g, `${lineEnding}${lineEnding}`).replace(/^(?:\r?\n)+/, "").trimEnd();
-  if (!next) {
-    unlinkSync5(path);
-  } else {
-    writeFileSync16(path, `${next}${lineEnding}`, "utf-8");
-  }
-  return { agent, path, action: "removed" };
-}
-var DOSU_RULE_SECTION_VERSION = 1, DOSU_RULE_SECTION_START, DOSU_RULE_SECTION_END = "<!-- dosu:rules:end -->", DOSU_RULE_SECTION_START_RE, CURSOR_FRONTMATTER = `---
-alwaysApply: true
----
-
-`, DOSU_RULE_URLS, FALLBACK_DOSU_RULE = `The team you are assisting maintains shared knowledge in Dosu: consult it to build on prior work, and contribute durable knowledge so future teammates and agents do not have to rediscover it. Always use only tools currently listed by the server.
-
-When \`read_knowledge\` is listed, call it before non-trivial code or documentation work involving architecture, conventions, prior decisions, gotchas, incidents, ownership, or branch history. **If unsure whether relevant context exists, read first.** Pass \`repo\` and \`branch\` when available. Skip generic questions, trivial or self-contained edits, and context already injected by Dosu.
-
-When \`write_knowledge\` is listed, use it after the task for durable, non-obvious knowledge that future work would otherwise have to rediscover. Do not save task or PR summaries, progress, test results, obvious facts, speculation, duplicates, or sensitive data. **If nothing durable was learned, do not write.**
-
-Use \`review_knowledge\` only when the user asks to inspect or manage pending knowledge. Preview one item at a time and require explicit confirmation before making changes.
-
-When \`read_knowledge\` or \`write_knowledge\` returned a \`receipt_item_id\` this turn, call \`finalize_session_knowledge\` exactly once at the end of the turn — after completing the task, immediately before your final reply — passing all receipt_item_ids from this turn. Never call it when the current turn produced no receipt_item_id, and never call it more than once per turn.
-`, RULE_TARGETS;
-var init_installer = __esm(() => {
-  DOSU_RULE_SECTION_START = `<!-- dosu:rules:start v${DOSU_RULE_SECTION_VERSION} -->`;
-  DOSU_RULE_SECTION_START_RE = /<!-- dosu:rules:start(?: v\d+)? -->/;
-  DOSU_RULE_URLS = [
-    "https://raw.githubusercontent.com/dosu-ai/dosu-cli/main/rules/dosu.md",
-    "https://raw.githubusercontent.com/dosu-ai/dosu-cli/master/rules/dosu.md"
-  ];
-  RULE_TARGETS = {
-    claude: {
-      kind: "file",
-      path: () => join40(claudeConfigDir4(), "rules", "dosu.md")
-    },
-    cursor: {
-      kind: "file",
-      path: () => join40(homedir12(), ".cursor", "rules", "dosu.mdc"),
-      cursorFrontmatter: true
-    },
-    codex: {
-      kind: "section",
-      path: () => join40(codexHome4(), "AGENTS.md")
-    },
-    opencode: {
-      kind: "section",
-      path: () => join40(homedir12(), ".config", "opencode", "AGENTS.md")
-    },
-    gemini: {
-      kind: "section",
-      path: () => join40(homedir12(), ".gemini", "GEMINI.md")
-    },
-    antigravity: {
-      kind: "section",
-      path: () => join40(homedir12(), ".gemini", "GEMINI.md")
-    }
-  };
-});
-
-// src/setup/agents-md-step.ts
-import { execSync as execSync2 } from "node:child_process";
-import { existsSync as existsSync26, readFileSync as readFileSync25, writeFileSync as writeFileSync17 } from "node:fs";
-import { join as join41 } from "node:path";
-function inGitWorkTree(cwd = process.cwd()) {
-  try {
-    const stdout = execSync2("git rev-parse --is-inside-work-tree", {
-      cwd,
-      stdio: ["ignore", "pipe", "ignore"]
-    });
-    return stdout.toString().trim() === "true";
-  } catch {
-    return false;
-  }
-}
-function dosuAgentsSectionState(cwd = process.cwd()) {
-  try {
-    const path = join41(cwd, "AGENTS.md");
-    if (!existsSync26(path))
-      return "missing";
-    const content = readFileSync25(path, "utf-8");
-    const startMatch = content.match(SECTION_START_RE);
-    if (!startMatch || !content.includes(DOSU_SECTION_END))
-      return "missing";
-    return Number(startMatch[1] ?? 0) >= DOSU_SECTION_VERSION ? "current" : "outdated";
-  } catch {
-    return "missing";
-  }
-}
-function lineEndingFor2(content) {
-  return content.includes(`\r
-`) ? `\r
-` : `
-`;
-}
-function renderDosuAgentsSection(content, lineEnding) {
-  const body = content.trim().replace(/\r?\n/g, lineEnding);
-  return `${DOSU_SECTION_START}${lineEnding}${body}${lineEnding}${DOSU_SECTION_END}`;
-}
-function buildDosuAgentsSection(content = FALLBACK_DOSU_RULE) {
-  return renderDosuAgentsSection(content, `
-`);
-}
-function findSection2(content) {
-  const startMatch = content.match(SECTION_START_RE);
-  const start = startMatch?.index ?? -1;
-  const end = content.indexOf(DOSU_SECTION_END, Math.max(start, 0));
-  if (start === -1 && end === -1)
-    return null;
-  if (start === -1 || end < start) {
-    throw new Error("Dosu AGENTS.md markers are incomplete; refusing to overwrite the file");
-  }
-  return { start, end };
-}
-function upsertDosuAgentsSection(cwd = process.cwd(), content = FALLBACK_DOSU_RULE) {
-  const path = join41(cwd, "AGENTS.md");
-  if (!existsSync26(path)) {
-    const section = buildDosuAgentsSection(content);
-    writeFileSync17(path, `${section}
-`);
-    return { path, action: "created" };
-  }
-  const existing = readFileSync25(path, "utf-8");
-  const lineEnding = lineEndingFor2(existing);
-  const section = renderDosuAgentsSection(content, lineEnding);
-  const location = findSection2(existing);
-  let next;
-  if (location) {
-    next = existing.slice(0, location.start) + section + existing.slice(location.end + DOSU_SECTION_END.length);
-  } else {
-    next = `${existing.trimEnd()}${lineEnding}${lineEnding}${section}${lineEnding}`;
-  }
-  if (next === existing)
-    return { path, action: "unchanged" };
-  writeFileSync17(path, next);
-  return { path, action: "updated" };
-}
-async function stepUpdateAgentsMd(cwd = process.cwd(), content) {
-  logger.info("setup", "Step: update AGENTS.md");
-  try {
-    const result = upsertDosuAgentsSection(cwd, content ?? await fetchDosuRule());
-    logger.info("setup", `AGENTS.md ${result.action} at ${result.path}`);
-    const status = result.action === "unchanged" ? "already up to date" : result.action;
-    log2.success(formatSetupSummary("AGENTS.md", [{ path: result.path, status }]));
-    return true;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    logger.error("setup", `AGENTS.md update failed: ${msg}`);
-    log2.error(`Could not update AGENTS.md: ${msg}`);
-    return false;
-  }
-}
-var DOSU_SECTION_VERSION = 2, DOSU_SECTION_START, DOSU_SECTION_END = "<!-- dosu:mcp:end -->", SECTION_START_RE;
-var init_agents_md_step = __esm(() => {
-  init_logger();
-  init_installer();
-  init_prompts();
-  init_styles();
-  DOSU_SECTION_START = `<!-- dosu:mcp:start v${DOSU_SECTION_VERSION} -->`;
-  SECTION_START_RE = /<!-- dosu:mcp:start(?: v(\d+))? -->/;
+  import_picocolors32 = __toESM(require_picocolors(), 1);
 });
 
 // src/auth/errors.ts
@@ -63193,16 +62850,51 @@ var init_errors3 = __esm(() => {
 // src/mcp/constants.ts
 var MCP_PROVIDER_SLUG2 = "dosu_mcp";
 
+// src/debug/follow.ts
+import { closeSync as closeSync7, openSync as openSync7, readSync as readSync5, statSync as statSync9 } from "node:fs";
+function createLogFollower(path, emit) {
+  const sizeOf = () => {
+    try {
+      return statSync9(path).size;
+    } catch {
+      return 0;
+    }
+  };
+  let offset = sizeOf();
+  return {
+    poll() {
+      const size = sizeOf();
+      if (size < offset)
+        offset = 0;
+      if (size === offset)
+        return;
+      try {
+        const fd = openSync7(path, "r");
+        try {
+          const buf = Buffer.alloc(size - offset);
+          const read = readSync5(fd, buf, 0, buf.length, offset);
+          offset += read;
+          if (read > 0)
+            emit(buf.toString("utf-8", 0, read));
+        } finally {
+          closeSync7(fd);
+        }
+      } catch {}
+    }
+  };
+}
+var init_follow = () => {};
+
 // src/sessions/session-title.ts
-import { existsSync as existsSync27, mkdirSync as mkdirSync16, readFileSync as readFileSync26, renameSync as renameSync6, statSync as statSync9, writeFileSync as writeFileSync18 } from "node:fs";
-import { homedir as homedir13 } from "node:os";
-import { join as join42 } from "node:path";
+import { existsSync as existsSync26, mkdirSync as mkdirSync16, readFileSync as readFileSync25, renameSync as renameSync6, statSync as statSync10, writeFileSync as writeFileSync17 } from "node:fs";
+import { homedir as homedir12 } from "node:os";
+import { join as join41 } from "node:path";
 function cachePath2(configDir) {
-  return join42(configDir, CACHE_FILENAME5);
+  return join41(configDir, CACHE_FILENAME5);
 }
 function loadCacheFile2(configDir) {
   try {
-    const raw = JSON.parse(readFileSync26(cachePath2(configDir), "utf-8"));
+    const raw = JSON.parse(readFileSync25(cachePath2(configDir), "utf-8"));
     if (raw.schema_version !== CACHE_SCHEMA_VERSION2 || typeof raw.entries !== "object")
       return {};
     return raw.entries;
@@ -63212,12 +62904,12 @@ function loadCacheFile2(configDir) {
 }
 function saveCacheFile2(configDir, entries) {
   try {
-    if (!existsSync27(configDir))
+    if (!existsSync26(configDir))
       mkdirSync16(configDir, { recursive: true, mode: 448 });
     const path = cachePath2(configDir);
     const tmp = `${path}.${process.pid}.tmp`;
     const file = { schema_version: CACHE_SCHEMA_VERSION2, entries };
-    writeFileSync18(tmp, JSON.stringify(file), { mode: 384 });
+    writeFileSync17(tmp, JSON.stringify(file), { mode: 384 });
     renameSync6(tmp, path);
   } catch {}
 }
@@ -63250,15 +62942,15 @@ function claudeSummaryFromHead(text) {
   }
   return null;
 }
-function reconstructSession(harness, id, slug, home = homedir13(), exists = existsSync27) {
+function reconstructSession(harness, id, slug, home = homedir12(), exists = existsSync26) {
   if (!slug)
     return null;
   const candidates = [];
   if (harness === "claude") {
-    candidates.push(join42(home, ".claude", "projects", slug, `${id}.jsonl`));
+    candidates.push(join41(home, ".claude", "projects", slug, `${id}.jsonl`));
   } else if (harness === "cursor") {
-    const project = join42(home, ".cursor", "projects", slug);
-    candidates.push(join42(project, "agent-transcripts", id, `${id}.jsonl`), join42(project, "agent-transcripts", `${id}.jsonl`));
+    const project = join41(home, ".cursor", "projects", slug);
+    candidates.push(join41(project, "agent-transcripts", id, `${id}.jsonl`), join41(project, "agent-transcripts", `${id}.jsonl`));
   } else {
     return null;
   }
@@ -63270,14 +62962,14 @@ function reconstructSession(harness, id, slug, home = homedir13(), exists = exis
 }
 function readHead2(path) {
   try {
-    return readFileSync26(path, "utf-8").slice(0, 128 * 1024);
+    return readFileSync25(path, "utf-8").slice(0, 128 * 1024);
   } catch {
     return null;
   }
 }
 function fileMtime2(path) {
   try {
-    return statSync9(path).mtime.toISOString();
+    return statSync10(path).mtime.toISOString();
   } catch {
     return "";
   }
@@ -63350,7 +63042,7 @@ var init_alt_screen = __esm(() => {
 });
 
 // src/tui/activity-view.ts
-import { existsSync as existsSync28, readFileSync as readFileSync27 } from "node:fs";
+import { existsSync as existsSync27, readFileSync as readFileSync26 } from "node:fs";
 import { basename as basename5 } from "node:path";
 function reduceActivityViewKey(key) {
   if (key === "q" || key === ESC7 || key === CTRL_C4)
@@ -63491,15 +63183,15 @@ function statusLine(status) {
   if (status.running) {
     const since = status.startedAt ? ` · since ${localTime(status.startedAt)}` : "";
     const pid = status.pid !== undefined ? ` (pid ${status.pid})` : "";
-    return `\uD83D\uDCDA ${import_picocolors34.default.bold(brand("Studying sessions..."))}${import_picocolors34.default.dim(`${pid}${since}`)}`;
+    return `\uD83D\uDCDA ${import_picocolors33.default.bold(brand("Studying sessions..."))}${import_picocolors33.default.dim(`${pid}${since}`)}`;
   }
   if (status.state.paused) {
-    return `${import_picocolors34.default.yellow("○")} ${import_picocolors34.default.bold("Paused")} ${import_picocolors34.default.dim("· studying stays off until you resume")}`;
+    return `${import_picocolors33.default.yellow("○")} ${import_picocolors33.default.bold("Paused")} ${import_picocolors33.default.dim("· studying stays off until you resume")}`;
   }
   if (status.staleLock) {
-    return `${import_picocolors34.default.yellow("○")} ${import_picocolors34.default.bold("Not running")} ${import_picocolors34.default.dim("· a previous run exited without cleaning up")}`;
+    return `${import_picocolors33.default.yellow("○")} ${import_picocolors33.default.bold("Not running")} ${import_picocolors33.default.dim("· a previous run exited without cleaning up")}`;
   }
-  return `${import_picocolors34.default.dim("○")} ${import_picocolors34.default.bold("Idle")} ${import_picocolors34.default.dim("· hooks study new sessions automatically")}`;
+  return `${import_picocolors33.default.dim("○")} ${import_picocolors33.default.bold("Idle")} ${import_picocolors33.default.dim("· hooks study new sessions automatically")}`;
 }
 function progressLine(done, ready, width, notes = 0) {
   const total = done + ready;
@@ -63508,7 +63200,7 @@ function progressLine(done, ready, width, notes = 0) {
   const cells = Math.max(10, Math.min(30, width - 44));
   const ratio = Math.max(0, Math.min(1, done / total));
   const filled = Math.min(cells, Math.round(ratio * cells));
-  const bar = brand("█".repeat(filled)) + import_picocolors34.default.dim("░".repeat(cells - filled));
+  const bar = brand("█".repeat(filled)) + import_picocolors33.default.dim("░".repeat(cells - filled));
   const pct = Math.floor(ratio * 100);
   const suffix = notes > 0 ? ` · ${notes} suggested page${notes === 1 ? "" : "s"}` : "";
   return `${bar} ${done}/${total} studied · ${pct}%${suffix}`;
@@ -63547,17 +63239,17 @@ function confirmBox(queuedCount, backlog, width, mode = "start") {
   const verb = mode === "clear" ? "clear" : mode === "stop" ? "stop" : mode === "resume" ? "resume" : "start";
   const maxInner = Math.max(20, Math.min(width, contentWidth()) - 4);
   const rows = [
-    import_picocolors34.default.bold(brand(title)),
-    ...wrapLine(scope, maxInner, "").map((line) => import_picocolors34.default.dim(line)),
+    import_picocolors33.default.bold(brand(title)),
+    ...wrapLine(scope, maxInner, "").map((line) => import_picocolors33.default.dim(line)),
     "",
-    `${import_picocolors34.default.bold("enter")} ${verb} · ${import_picocolors34.default.bold("esc")} cancel`
+    `${import_picocolors33.default.bold("enter")} ${verb} · ${import_picocolors33.default.bold("esc")} cancel`
   ];
   const inner = Math.min(maxInner, Math.max(...rows.map(visibleWidth2)));
   const pad = (row) => row + " ".repeat(Math.max(0, inner - visibleWidth2(row)));
   return [
-    import_picocolors34.default.dim(`╭${"─".repeat(inner + 2)}╮`),
-    ...rows.map((row) => `${import_picocolors34.default.dim("│")} ${pad(row)} ${import_picocolors34.default.dim("│")}`),
-    import_picocolors34.default.dim(`╰${"─".repeat(inner + 2)}╯`)
+    import_picocolors33.default.dim(`╭${"─".repeat(inner + 2)}╮`),
+    ...rows.map((row) => `${import_picocolors33.default.dim("│")} ${pad(row)} ${import_picocolors33.default.dim("│")}`),
+    import_picocolors33.default.dim(`╰${"─".repeat(inner + 2)}╯`)
   ];
 }
 function buildActivityFrame(status, activity, width, backlog = null, pane = DEFAULT_PANE, queued = [], studiedBeforeRun = 0, open = [], runProgress = null, projectNames = {}, sessionNames = {}, frameLines) {
@@ -63573,7 +63265,7 @@ function buildActivityFrame(status, activity, width, backlog = null, pane = DEFA
     progress = progressLine(studiedDelta + stepDone, Math.max(0, backlog.ready - stepDone), width, runProgress?.notes ?? 0);
   }
   const refusal = !status.running && status.state.last_refusal;
-  const refusalLines = refusal ? wrapLine(`! Studying paused: ${refusal.message} (${localTime(refusal.at)})`, width).map((line) => import_picocolors34.default.yellow(line)) : [];
+  const refusalLines = refusal ? wrapLine(`! Studying paused: ${refusal.message} (${localTime(refusal.at)})`, width).map((line) => import_picocolors33.default.yellow(line)) : [];
   const fullRows = Boolean(pane.fullRows);
   const withName = (item, key) => projectNames[key] ? { ...item, project: projectNames[key] } : item;
   const latestPass = new Map;
@@ -63599,8 +63291,8 @@ function buildActivityFrame(status, activity, width, backlog = null, pane = DEFA
     breadcrumb(["home", "activity"], width),
     "",
     statusLine(status),
-    import_picocolors34.default.dim(studied),
-    ...queueDetail.length > 0 ? wrapLine(queueDetail.join(" · "), width).map((line) => import_picocolors34.default.dim(line)) : [],
+    import_picocolors33.default.dim(studied),
+    ...queueDetail.length > 0 ? wrapLine(queueDetail.join(" · "), width).map((line) => import_picocolors33.default.dim(line)) : [],
     ...progress ? [progress] : [],
     ...refusalLines,
     "",
@@ -63616,7 +63308,7 @@ function buildActivityFrame(status, activity, width, backlog = null, pane = DEFA
         status.running ? "s stop" : status.state.paused ? "s resume" : "s sync now",
         ...!status.running && status.state.watermark ? ["c clear"] : [],
         "esc back"
-      ].join(" · "), width, "").map((line) => import_picocolors34.default.dim(line))
+      ].join(" · "), width, "").map((line) => import_picocolors33.default.dim(line))
     ]
   ];
   const defaultHeight = fullRows ? ACTIVITY_VIEW_FULL_LIST_ROWS : ACTIVITY_VIEW_LIST_LINES;
@@ -63629,7 +63321,7 @@ function buildActivityFrame(status, activity, width, backlog = null, pane = DEFA
     ({ visible, above, below } = windowList(source, pane.scroll, height));
     display = visible.flatMap((row) => wrapRow(row, width));
   }
-  const listRows = display.length > 0 ? display.map((row) => import_picocolors34.default.dim(row)) : [import_picocolors34.default.dim(empty)];
+  const listRows = display.length > 0 ? display.map((row) => import_picocolors33.default.dim(row)) : [import_picocolors33.default.dim(empty)];
   const scrollParts = [];
   if (above > 0)
     scrollParts.push(`↑ ${above} earlier`);
@@ -63638,7 +63330,7 @@ function buildActivityFrame(status, activity, width, backlog = null, pane = DEFA
   const lines = [
     ...header,
     ...listRows,
-    ...scrollParts.length > 0 ? [import_picocolors34.default.dim(clip(scrollParts.join(" · "), width))] : [],
+    ...scrollParts.length > 0 ? [import_picocolors33.default.dim(clip(scrollParts.join(" · "), width))] : [],
     ...footer
   ];
   return { lines, listHeight: height };
@@ -63671,7 +63363,7 @@ function createRowNamer() {
         names.titles[key] = t;
     };
     for (const s of [...backlog.queued, ...backlog.open]) {
-      if (!existsSync28(s.path))
+      if (!existsSync27(s.path))
         continue;
       const key = `${s.harness}/${s.id}`;
       const dir = dirs.resolve(s);
@@ -63708,7 +63400,7 @@ function createRowNamer() {
 }
 function defaultReadLog2() {
   try {
-    return readFileSync27(logger.getLogPath(), "utf-8");
+    return readFileSync26(logger.getLogPath(), "utf-8");
   } catch {
     return "";
   }
@@ -63893,7 +63585,7 @@ ${CLEAR_BELOW}`);
     input.on("data", onData);
   });
 }
-var import_picocolors34, ESC7, HIDE_CURSOR3, SHOW_CURSOR3, CTRL_C4, KEY_UP4, KEY_DOWN4, KEY_RIGHT3, KEY_LEFT3, CURSOR_HOME, CLEAR_BELOW, CLEAR_EOL, ACTIVITY_VIEW_POLL_MS = 500, ACTIVITY_VIEW_LIST_LINES = 10, ACTIVITY_VIEW_FULL_LIST_ROWS = 5, ACTIVITY_VIEW_BUFFER_LINES = 200, ACTIVITY_VIEW_TABS, DEFAULT_PANE, TITLE_READS_PER_DRAW = 25;
+var import_picocolors33, ESC7, HIDE_CURSOR3, SHOW_CURSOR3, CTRL_C4, KEY_UP4, KEY_DOWN4, KEY_RIGHT3, KEY_LEFT3, CURSOR_HOME, CLEAR_BELOW, CLEAR_EOL, ACTIVITY_VIEW_POLL_MS = 500, ACTIVITY_VIEW_LIST_LINES = 10, ACTIVITY_VIEW_FULL_LIST_ROWS = 5, ACTIVITY_VIEW_BUFFER_LINES = 200, ACTIVITY_VIEW_TABS, DEFAULT_PANE, TITLE_READS_PER_DRAW = 25;
 var init_activity_view = __esm(() => {
   init_follow();
   init_logger();
@@ -63908,7 +63600,7 @@ var init_activity_view = __esm(() => {
   init_alt_screen();
   init_layout();
   init_menu();
-  import_picocolors34 = __toESM(require_picocolors(), 1);
+  import_picocolors33 = __toESM(require_picocolors(), 1);
   ESC7 = String.fromCharCode(27);
   HIDE_CURSOR3 = `${ESC7}[?25l`;
   SHOW_CURSOR3 = `${ESC7}[?25h`;
@@ -63924,6 +63616,284 @@ var init_activity_view = __esm(() => {
   DEFAULT_PANE = { tab: "activity", scroll: 0 };
 });
 
+// src/rules/installer.ts
+import { existsSync as existsSync28, mkdirSync as mkdirSync17, readFileSync as readFileSync27, unlinkSync as unlinkSync5, writeFileSync as writeFileSync18 } from "node:fs";
+import { homedir as homedir13 } from "node:os";
+import { dirname as dirname12, join as join42 } from "node:path";
+function claudeConfigDir4() {
+  return process.env.CLAUDE_CONFIG_DIR || join42(homedir13(), ".claude");
+}
+function codexHome4() {
+  return process.env.CODEX_HOME || join42(homedir13(), ".codex");
+}
+function isRuleAgent(agent) {
+  return Object.hasOwn(RULE_TARGETS, agent);
+}
+function rulePathForAgent(agent) {
+  return isRuleAgent(agent) ? RULE_TARGETS[agent].path() : null;
+}
+function normalizeRule(content) {
+  return `${content.trim()}
+`;
+}
+async function fetchDosuRule(fetchImpl = globalThis.fetch) {
+  for (const url of DOSU_RULE_URLS) {
+    try {
+      const response = await fetchImpl(url);
+      if (!response.ok)
+        continue;
+      const content = await response.text();
+      if (content.trim())
+        return normalizeRule(content);
+    } catch {}
+  }
+  return normalizeRule(FALLBACK_DOSU_RULE);
+}
+function ensureParent(path) {
+  mkdirSync17(dirname12(path), { recursive: true });
+}
+function writeIfChanged(path, content) {
+  if (!existsSync28(path)) {
+    ensureParent(path);
+    writeFileSync18(path, content, "utf-8");
+    return "created";
+  }
+  if (readFileSync27(path, "utf-8") === content)
+    return "unchanged";
+  writeFileSync18(path, content, "utf-8");
+  return "updated";
+}
+function findSection(content) {
+  const startMatch = content.match(DOSU_RULE_SECTION_START_RE);
+  const start = startMatch?.index ?? -1;
+  const end = content.indexOf(DOSU_RULE_SECTION_END, Math.max(start, 0));
+  if (start === -1 && end === -1)
+    return null;
+  if (start === -1 || end < start) {
+    throw new Error("Dosu rule markers are incomplete; refusing to overwrite the instruction file");
+  }
+  return { start, end };
+}
+function lineEndingFor(content) {
+  return content.includes(`\r
+`) ? `\r
+` : `
+`;
+}
+function buildSection(content, lineEnding = `
+`) {
+  const body = content.trimEnd().replace(/\r?\n/g, lineEnding);
+  return `${DOSU_RULE_SECTION_START}${lineEnding}${body}${lineEnding}${DOSU_RULE_SECTION_END}`;
+}
+function upsertSection(path, content) {
+  if (!existsSync28(path)) {
+    const section = buildSection(content);
+    ensureParent(path);
+    writeFileSync18(path, `${section}
+`, "utf-8");
+    return "created";
+  }
+  const existing = readFileSync27(path, "utf-8");
+  const lineEnding = lineEndingFor(existing);
+  const section = buildSection(content, lineEnding);
+  const location = findSection(existing);
+  let next;
+  if (location) {
+    next = existing.slice(0, location.start) + section + existing.slice(location.end + DOSU_RULE_SECTION_END.length);
+  } else {
+    const separator = existing.length > 0 && !existing.endsWith(lineEnding) ? `${lineEnding}${lineEnding}` : existing.length > 0 ? lineEnding : "";
+    next = `${existing}${separator}${section}${lineEnding}`;
+  }
+  if (next === existing)
+    return "unchanged";
+  writeFileSync18(path, next, "utf-8");
+  return "updated";
+}
+function installRuleForAgent(agent, content) {
+  if (!isRuleAgent(agent))
+    return null;
+  const target = RULE_TARGETS[agent];
+  const path = target.path();
+  const normalized = normalizeRule(content);
+  const action = target.kind === "file" ? writeIfChanged(path, target.cursorFrontmatter ? `${CURSOR_FRONTMATTER}${normalized}` : normalized) : upsertSection(path, normalized);
+  return { agent, path, action };
+}
+function removeRuleForAgent(agent) {
+  if (!isRuleAgent(agent))
+    return null;
+  const target = RULE_TARGETS[agent];
+  const path = target.path();
+  if (!existsSync28(path))
+    return { agent, path, action: "not_found" };
+  if (target.kind === "file") {
+    unlinkSync5(path);
+    return { agent, path, action: "removed" };
+  }
+  const existing = readFileSync27(path, "utf-8");
+  const lineEnding = lineEndingFor(existing);
+  const location = findSection(existing);
+  if (!location)
+    return { agent, path, action: "not_found" };
+  const next = (existing.slice(0, location.start) + existing.slice(location.end + DOSU_RULE_SECTION_END.length)).replace(/(?:\r?\n){3,}/g, `${lineEnding}${lineEnding}`).replace(/^(?:\r?\n)+/, "").trimEnd();
+  if (!next) {
+    unlinkSync5(path);
+  } else {
+    writeFileSync18(path, `${next}${lineEnding}`, "utf-8");
+  }
+  return { agent, path, action: "removed" };
+}
+var DOSU_RULE_SECTION_VERSION = 1, DOSU_RULE_SECTION_START, DOSU_RULE_SECTION_END = "<!-- dosu:rules:end -->", DOSU_RULE_SECTION_START_RE, CURSOR_FRONTMATTER = `---
+alwaysApply: true
+---
+
+`, DOSU_RULE_URLS, FALLBACK_DOSU_RULE = `The team you are assisting maintains shared knowledge in Dosu: consult it to build on prior work, and contribute durable knowledge so future teammates and agents do not have to rediscover it. Always use only tools currently listed by the server.
+
+When \`read_knowledge\` is listed, call it before non-trivial code or documentation work involving architecture, conventions, prior decisions, gotchas, incidents, ownership, or branch history. **If unsure whether relevant context exists, read first.** Pass \`repo\` and \`branch\` when available. Skip generic questions, trivial or self-contained edits, and context already injected by Dosu.
+
+When \`write_knowledge\` is listed, use it after the task for durable, non-obvious knowledge that future work would otherwise have to rediscover. Do not save task or PR summaries, progress, test results, obvious facts, speculation, duplicates, or sensitive data. **If nothing durable was learned, do not write.**
+
+Use \`review_knowledge\` only when the user asks to inspect or manage pending knowledge. Preview one item at a time and require explicit confirmation before making changes.
+
+When \`read_knowledge\` or \`write_knowledge\` returned a \`receipt_item_id\` this turn, call \`finalize_session_knowledge\` exactly once at the end of the turn — after completing the task, immediately before your final reply — passing all receipt_item_ids from this turn. Never call it when the current turn produced no receipt_item_id, and never call it more than once per turn.
+`, RULE_TARGETS;
+var init_installer = __esm(() => {
+  DOSU_RULE_SECTION_START = `<!-- dosu:rules:start v${DOSU_RULE_SECTION_VERSION} -->`;
+  DOSU_RULE_SECTION_START_RE = /<!-- dosu:rules:start(?: v\d+)? -->/;
+  DOSU_RULE_URLS = [
+    "https://raw.githubusercontent.com/dosu-ai/dosu-cli/main/rules/dosu.md",
+    "https://raw.githubusercontent.com/dosu-ai/dosu-cli/master/rules/dosu.md"
+  ];
+  RULE_TARGETS = {
+    claude: {
+      kind: "file",
+      path: () => join42(claudeConfigDir4(), "rules", "dosu.md")
+    },
+    cursor: {
+      kind: "file",
+      path: () => join42(homedir13(), ".cursor", "rules", "dosu.mdc"),
+      cursorFrontmatter: true
+    },
+    codex: {
+      kind: "section",
+      path: () => join42(codexHome4(), "AGENTS.md")
+    },
+    opencode: {
+      kind: "section",
+      path: () => join42(homedir13(), ".config", "opencode", "AGENTS.md")
+    },
+    gemini: {
+      kind: "section",
+      path: () => join42(homedir13(), ".gemini", "GEMINI.md")
+    },
+    antigravity: {
+      kind: "section",
+      path: () => join42(homedir13(), ".gemini", "GEMINI.md")
+    }
+  };
+});
+
+// src/setup/agents-md-step.ts
+import { execSync as execSync2 } from "node:child_process";
+import { existsSync as existsSync29, readFileSync as readFileSync28, writeFileSync as writeFileSync19 } from "node:fs";
+import { join as join43 } from "node:path";
+function inGitWorkTree(cwd = process.cwd()) {
+  try {
+    const stdout = execSync2("git rev-parse --is-inside-work-tree", {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return stdout.toString().trim() === "true";
+  } catch {
+    return false;
+  }
+}
+function dosuAgentsSectionState(cwd = process.cwd()) {
+  try {
+    const path = join43(cwd, "AGENTS.md");
+    if (!existsSync29(path))
+      return "missing";
+    const content = readFileSync28(path, "utf-8");
+    const startMatch = content.match(SECTION_START_RE);
+    if (!startMatch || !content.includes(DOSU_SECTION_END))
+      return "missing";
+    return Number(startMatch[1] ?? 0) >= DOSU_SECTION_VERSION ? "current" : "outdated";
+  } catch {
+    return "missing";
+  }
+}
+function lineEndingFor2(content) {
+  return content.includes(`\r
+`) ? `\r
+` : `
+`;
+}
+function renderDosuAgentsSection(content, lineEnding) {
+  const body = content.trim().replace(/\r?\n/g, lineEnding);
+  return `${DOSU_SECTION_START}${lineEnding}${body}${lineEnding}${DOSU_SECTION_END}`;
+}
+function buildDosuAgentsSection(content = FALLBACK_DOSU_RULE) {
+  return renderDosuAgentsSection(content, `
+`);
+}
+function findSection2(content) {
+  const startMatch = content.match(SECTION_START_RE);
+  const start = startMatch?.index ?? -1;
+  const end = content.indexOf(DOSU_SECTION_END, Math.max(start, 0));
+  if (start === -1 && end === -1)
+    return null;
+  if (start === -1 || end < start) {
+    throw new Error("Dosu AGENTS.md markers are incomplete; refusing to overwrite the file");
+  }
+  return { start, end };
+}
+function upsertDosuAgentsSection(cwd = process.cwd(), content = FALLBACK_DOSU_RULE) {
+  const path = join43(cwd, "AGENTS.md");
+  if (!existsSync29(path)) {
+    const section = buildDosuAgentsSection(content);
+    writeFileSync19(path, `${section}
+`);
+    return { path, action: "created" };
+  }
+  const existing = readFileSync28(path, "utf-8");
+  const lineEnding = lineEndingFor2(existing);
+  const section = renderDosuAgentsSection(content, lineEnding);
+  const location = findSection2(existing);
+  let next;
+  if (location) {
+    next = existing.slice(0, location.start) + section + existing.slice(location.end + DOSU_SECTION_END.length);
+  } else {
+    next = `${existing.trimEnd()}${lineEnding}${lineEnding}${section}${lineEnding}`;
+  }
+  if (next === existing)
+    return { path, action: "unchanged" };
+  writeFileSync19(path, next);
+  return { path, action: "updated" };
+}
+async function stepUpdateAgentsMd(cwd = process.cwd(), content) {
+  logger.info("setup", "Step: update AGENTS.md");
+  try {
+    const result = upsertDosuAgentsSection(cwd, content ?? await fetchDosuRule());
+    logger.info("setup", `AGENTS.md ${result.action} at ${result.path}`);
+    const status = result.action === "unchanged" ? "already up to date" : result.action;
+    log2.success(formatSetupSummary("AGENTS.md", [{ path: result.path, status }]));
+    return true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.error("setup", `AGENTS.md update failed: ${msg}`);
+    log2.error(`Could not update AGENTS.md: ${msg}`);
+    return false;
+  }
+}
+var DOSU_SECTION_VERSION = 2, DOSU_SECTION_START, DOSU_SECTION_END = "<!-- dosu:mcp:end -->", SECTION_START_RE;
+var init_agents_md_step = __esm(() => {
+  init_logger();
+  init_installer();
+  init_prompts();
+  init_styles();
+  DOSU_SECTION_START = `<!-- dosu:mcp:start v${DOSU_SECTION_VERSION} -->`;
+  SECTION_START_RE = /<!-- dosu:mcp:start(?: v(\d+))? -->/;
+});
+
 // src/setup/analytics.ts
 async function trackCliOnboardingEvent(cfg, onboardingRunID, event, properties = {}) {
   try {
@@ -65391,7 +65361,7 @@ async function stepSelectTools(detected) {
     initialValues: preselected,
     statusFor: (id, picked) => {
       if (configuredMap.get(id))
-        return picked ? dim("configured") : import_picocolors35.default.yellow("will remove");
+        return picked ? dim("configured") : import_picocolors34.default.yellow("will remove");
       return picked ? brand("will configure") : undefined;
     },
     summary: (picked) => {
@@ -65566,7 +65536,7 @@ ${dim(wrapLog("Run it inside a session to keep that session out of studying. Rem
     log2.success("All agents already configured. No changes needed.");
   }
 }
-var import_picocolors35, OAUTH_ANALYTICS_REASONS, SETUP_HANDSHAKE_TIMEOUT_MS = 1800000, LIBRARY_SELECT_CANCELLED;
+var import_picocolors34, OAUTH_ANALYTICS_REASONS, SETUP_HANDSHAKE_TIMEOUT_MS = 1800000, LIBRARY_SELECT_CANCELLED;
 var init_flow2 = __esm(() => {
   init_dist();
   init_errors3();
@@ -65591,7 +65561,7 @@ var init_flow2 = __esm(() => {
   init_github_step();
   init_rules_step();
   init_styles();
-  import_picocolors35 = __toESM(require_picocolors(), 1);
+  import_picocolors34 = __toESM(require_picocolors(), 1);
   OAUTH_ANALYTICS_REASONS = new Set([
     "access_denied",
     "bad_oauth_state",
@@ -65605,6 +65575,298 @@ var init_flow2 = __esm(() => {
   LIBRARY_SELECT_CANCELLED = Symbol("library-select-cancelled");
 });
 
+// src/commands/upgrade.ts
+import { spawnSync } from "node:child_process";
+import { realpathSync as realpathSync2 } from "node:fs";
+import { homedir as homedir14 } from "node:os";
+import { posix, win32 as win322 } from "node:path";
+function isAbsoluteCommandProcessor(value) {
+  return Boolean(value && win322.isAbsolute(value) && win322.basename(value).toLowerCase() === "cmd.exe");
+}
+function windowsCommandProcessor(env = process.env) {
+  if (isAbsoluteCommandProcessor(env.ComSpec))
+    return env.ComSpec;
+  const systemRoot = env.SystemRoot && win322.isAbsolute(env.SystemRoot) ? env.SystemRoot : "C:\\Windows";
+  return win322.join(systemRoot, "System32", "cmd.exe");
+}
+function safePackageManagerEnv(env) {
+  return {
+    ...env,
+    COREPACK_ENABLE_NETWORK: "0",
+    COREPACK_ENABLE_PROJECT_SPEC: "0",
+    YARN_IGNORE_PATH: "1"
+  };
+}
+function buildPackageManagerInvocation(manager, action, platform = process.platform, comSpec, env = process.env) {
+  const args = action === "locate" ? PACKAGE_MANAGERS[manager].locateArgs : PACKAGE_MANAGERS[manager].installArgs;
+  const safeEnv = safePackageManagerEnv(env);
+  if (platform === "win32") {
+    return {
+      command: isAbsoluteCommandProcessor(comSpec) ? comSpec : windowsCommandProcessor(env),
+      args: ["/d", "/s", "/c", [manager, ...args].join(" ")],
+      env: { ...safeEnv, NoDefaultCurrentDirectoryInExePath: "1" }
+    };
+  }
+  return { command: manager, args: [...args], env: safeEnv };
+}
+function packageRoots(manager, platform, comSpec, env, cwd) {
+  const invocation = buildPackageManagerInvocation(manager, "locate", platform, comSpec, env);
+  const result = spawnSync(invocation.command, invocation.args, {
+    cwd,
+    encoding: "utf8",
+    env: invocation.env,
+    shell: false,
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: PROBE_TIMEOUT_MS
+  });
+  if (result.status !== 0 || typeof result.stdout !== "string")
+    return [];
+  const path = platform === "win32" ? win322 : posix;
+  const lines = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => path.isAbsolute(line));
+  if (manager === "pnpm") {
+    return lines.filter((line) => path.basename(line) === "cli" && path.basename(path.dirname(line)) === "@dosu" && path.basename(path.dirname(path.dirname(line))) === "node_modules");
+  }
+  if (lines.length !== 1)
+    return [];
+  return [
+    manager === "npm" ? path.join(lines[0], "@dosu", "cli") : path.join(lines[0], "node_modules", "@dosu", "cli")
+  ];
+}
+function owningPackageManager(entrypoint, platform, comSpec, env = process.env, cwd = homedir14()) {
+  const path = platform === "win32" ? win322 : posix;
+  if (!entrypoint || !path.isAbsolute(entrypoint))
+    return null;
+  let realEntrypoint;
+  try {
+    realEntrypoint = realpathSync2(entrypoint);
+  } catch {
+    return null;
+  }
+  const owners = Object.keys(PACKAGE_MANAGERS).filter((manager) => packageRoots(manager, platform, comSpec, env, cwd).some((root) => {
+    try {
+      const relative = path.relative(realpathSync2(root), realEntrypoint);
+      return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    } catch {
+      return false;
+    }
+  }));
+  return owners.length === 1 ? owners[0] : null;
+}
+function upgradePlan(channel, manager, platform, comSpec, env = process.env) {
+  if (channel === "homebrew") {
+    return {
+      label: "Homebrew",
+      command: "brew",
+      args: ["upgrade", "dosu-ai/dosu/dosu"],
+      manualCommand: BREW_MANUAL_COMMAND
+    };
+  }
+  if (channel === "npm" && manager) {
+    const invocation = buildPackageManagerInvocation(manager, "install", platform, comSpec, env);
+    return {
+      label: PACKAGE_MANAGERS[manager].label,
+      ...invocation,
+      manualCommand: [manager, ...PACKAGE_MANAGERS[manager].installArgs].join(" ")
+    };
+  }
+  return null;
+}
+function printNonGlobalPackageGuidance() {
+  console.log("This Dosu copy is not a uniquely identified global package installation, so it was not changed.");
+  console.log(`
+Run the latest version without installing:
+  ${NPX_COMMAND}`);
+  console.log(`
+Or install Dosu globally with your package manager:`);
+  for (const manager of Object.keys(PACKAGE_MANAGERS)) {
+    console.log(`  ${manager} ${PACKAGE_MANAGERS[manager].installArgs.join(" ")}`);
+  }
+}
+function runUpgrade(channel = INSTALL_CHANNEL, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? homedir14();
+  let manager = null;
+  if (channel === "npm") {
+    if (isNpxInvocation(channel, env)) {
+      printNonGlobalPackageGuidance();
+      return 1;
+    }
+    manager = owningPackageManager(options.entrypoint ?? process.argv[1], platform, options.comSpec, env, cwd);
+    if (!manager) {
+      if (env.DOSU_DEV === "true") {
+        console.log("DOSU_DEV=true and this copy is not a global package: skipping the package install.");
+        return 0;
+      }
+      printNonGlobalPackageGuidance();
+      return 1;
+    }
+  }
+  const plan = upgradePlan(channel, manager, platform, options.comSpec, env);
+  if (!plan) {
+    console.log("Automatic upgrades are not available for this installation yet.");
+    console.log(`Download the latest release:
+  ${RELEASES_URL}`);
+    return 1;
+  }
+  console.log(`Updating Dosu with ${plan.label}...`);
+  console.log(`  ${plan.manualCommand}
+`);
+  const result = spawnSync(plan.command, plan.args, {
+    ...channel === "npm" ? { cwd } : {},
+    ...plan.env ? { env: plan.env } : {},
+    shell: false,
+    stdio: "inherit"
+  });
+  if (result.error || result.status !== 0) {
+    console.error(`
+Could not update Dosu automatically.`);
+    console.error(`Run manually:
+  ${plan.manualCommand}`);
+    return result.status && result.status > 0 ? result.status : 1;
+  }
+  console.log(import_picocolors35.default.green(`
+✓ Update command completed.`));
+  console.log('Run "dosu --version" to verify.');
+  return 0;
+}
+function postUpgradeArgs(fromVersion = VERSION) {
+  return ["upgrade", "--finish", fromVersion];
+}
+function newBinaryInvocation(channel, args, entrypoint = process.argv[1], execPath = process.execPath) {
+  if (channel === "npm") {
+    return entrypoint ? { command: execPath, args: [entrypoint, ...args] } : null;
+  }
+  if (channel === "homebrew") {
+    return { command: "dosu", args };
+  }
+  return null;
+}
+function isInteractiveTerminal() {
+  return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+function finishWithNewBinary(channel, options) {
+  const invocation = newBinaryInvocation(channel, postUpgradeArgs(), options.entrypoint ?? process.argv[1]);
+  if (!invocation) {
+    console.error(SETUP_FALLBACK);
+    return;
+  }
+  const result = spawnSync(invocation.command, invocation.args, {
+    cwd: options.cwd ?? homedir14(),
+    shell: false,
+    stdio: "inherit"
+  });
+  if (result.error || result.status !== 0) {
+    console.error(SETUP_FALLBACK);
+  }
+}
+async function completeUpgrade(channel = INSTALL_CHANNEL, options = {}) {
+  const status = runUpgrade(channel, options);
+  if (status !== 0)
+    return status;
+  finishWithNewBinary(channel, options);
+  return 0;
+}
+async function finishUpgrade(from, options = {}) {
+  const previous = SEMVER.test(from) ? from : null;
+  if (!needsMcpRefresh(previous, VERSION)) {
+    checkForSkillUpdates();
+    writeMcpRefreshCache({ version: VERSION });
+    console.log(import_picocolors35.default.green(`✓ Dosu ${VERSION} is ready. Your AI agents need no changes.`));
+    return 0;
+  }
+  if (options.interactive ?? isInteractiveTerminal()) {
+    console.log(`
+This update changes how agents connect to Dosu. Running setup...
+`);
+    await Promise.resolve().then(() => init_flow2());
+    await runSetup();
+    return 0;
+  }
+  checkForSkillUpdates();
+  const cfg = loadConfigNonBlocking();
+  if (!cfg || !canRefreshMcp(cfg)) {
+    console.error(SETUP_FALLBACK);
+    return 0;
+  }
+  console.log(`
+Refreshing agent MCP configs with the new version...`);
+  const result = refreshConfiguredProviders(cfg);
+  writeMcpRefreshCache({ version: VERSION });
+  for (const provider of result.updated)
+    console.log(`  ✓ ${provider.name()}`);
+  for (const { provider, error } of result.failed) {
+    console.log(`  ✗ ${provider.name()}: ${error.message}`);
+  }
+  if (result.failed.length > 0)
+    console.error(SETUP_FALLBACK);
+  return 0;
+}
+function setAutoUpdate(value) {
+  const normalized = value.trim().toLowerCase();
+  if (normalized !== "on" && normalized !== "off") {
+    console.error(`Invalid --auto value '${value}' (expected 'on' or 'off').`);
+    return 2;
+  }
+  if (!setAutoUpdateEnabled(normalized === "on")) {
+    console.error("Could not save the auto-update setting.");
+    return 1;
+  }
+  if (normalized === "off") {
+    console.log('Automatic updates are off. Run "dosu upgrade" to update by hand.');
+  } else if (autoUpdateDisabledReason() === "env") {
+    console.log(`Automatic updates are on, but ${AUTO_UPDATE_ENV} still disables them here.`);
+  } else {
+    console.log("Automatic updates are on.");
+  }
+  return 0;
+}
+function upgradeCommand() {
+  return new Command("upgrade").description("Update Dosu to the latest version, re-running setup when the update changes agent config").option("--auto <on|off>", "Turn automatic background updates on or off").addOption(new Option("--background").hideHelp()).addOption(new Option("--finish <from>").hideHelp()).action(async (opts) => {
+    let status;
+    if (opts.auto !== undefined) {
+      status = setAutoUpdate(opts.auto);
+    } else if (opts.background) {
+      status = runBackgroundUpgrade(() => runUpgrade());
+    } else if (opts.finish !== undefined) {
+      status = await finishUpgrade(opts.finish);
+    } else {
+      status = await completeUpgrade();
+    }
+    if (status !== 0)
+      process.exitCode = status;
+  });
+}
+var import_picocolors35, PACKAGE_NAME = "@dosu/cli", LATEST_PACKAGE, BREW_MANUAL_COMMAND = "brew upgrade dosu-ai/dosu/dosu", NPX_COMMAND = "npx -y @dosu/cli@latest", PROBE_TIMEOUT_MS = 5000, RELEASES_URL = "https://github.com/dosu-ai/dosu-cli/releases/latest", PACKAGE_MANAGERS, SETUP_FALLBACK = 'Run "dosu setup" to finish updating your AI agents.', SEMVER;
+var init_upgrade = __esm(() => {
+  init_commander();
+  init_config();
+  init_refresh();
+  init_auto_update();
+  init_mcp_refresh_check();
+  init_skill_update_check();
+  import_picocolors35 = __toESM(require_picocolors(), 1);
+  LATEST_PACKAGE = `${PACKAGE_NAME}@latest`;
+  PACKAGE_MANAGERS = {
+    npm: {
+      label: "npm",
+      locateArgs: ["root", "-g"],
+      installArgs: ["install", "-g", LATEST_PACKAGE]
+    },
+    pnpm: {
+      label: "pnpm",
+      locateArgs: ["list", "-g", "--depth=0", "--parseable", PACKAGE_NAME],
+      installArgs: ["add", "-g", LATEST_PACKAGE]
+    },
+    yarn: {
+      label: "Yarn Classic",
+      locateArgs: ["--silent", "global", "dir"],
+      installArgs: ["global", "add", LATEST_PACKAGE]
+    }
+  };
+  SEMVER = /^\d+\.\d+\.\d+/;
+});
+
 // src/tui/analytics-view.ts
 function analyticsListHeight(rows) {
   const room = frameMaxLines(rows) - ANALYTICS_VIEW_CHROME_LINES;
@@ -66288,7 +66550,7 @@ var init_pages_view = __esm(() => {
 });
 
 // src/tui/tui.ts
-import { homedir as homedir14 } from "node:os";
+import { homedir as homedir15 } from "node:os";
 import { basename as basename6 } from "node:path";
 async function probeSession(cfg) {
   if (!isAuthenticated(cfg) || !isTokenExpired(cfg))
@@ -66553,7 +66815,7 @@ async function runSettings(cfg) {
   }
 }
 function displayDir(dir) {
-  const home = homedir14();
+  const home = homedir15();
   return dir === home ? "~" : dir.startsWith(`${home}/`) ? `~${dir.slice(home.length)}` : dir;
 }
 function discoverProjectDirs() {
@@ -67263,7 +67525,7 @@ var init_flow3 = __esm(() => {
 });
 
 // src/cli/cli.ts
-import { readFileSync as readFileSync28, unlinkSync as unlinkSync6 } from "node:fs";
+import { readFileSync as readFileSync29, unlinkSync as unlinkSync6 } from "node:fs";
 function shouldRunBackgroundChecks(actionName) {
   return actionName !== "upgrade";
 }
@@ -67709,7 +67971,7 @@ Use 'dosu mcp add <agent>' to add Dosu MCP to a tool.`);
     }
     if (opts.follow) {
       try {
-        const lines = readFileSync28(logPath, "utf-8").split(`
+        const lines = readFileSync29(logPath, "utf-8").split(`
 `);
         if (lines.at(-1) === "")
           lines.pop();
@@ -67725,7 +67987,7 @@ Use 'dosu mcp add <agent>' to add Dosu MCP to a tool.`);
     if (opts.tail !== undefined) {
       const n = typeof opts.tail === "string" ? parseInt(opts.tail, 10) || 50 : 50;
       try {
-        const content = readFileSync28(logPath, "utf-8");
+        const content = readFileSync29(logPath, "utf-8");
         const lines = content.split(`
 `);
         console.log(lines.slice(-n).join(`
@@ -67851,4 +68113,4 @@ main().catch((err) => {
   process.exit(1);
 });
 
-//# debugId=9d93d312-f9af-7e47-6475-6e2164756e21
+//# debugId=41cac967-78f1-f75a-6475-6e2164756e21