@kevin0181/memoc 1.0.8 → 1.1.0

package/bin/cli.js

@@ -188,338 +188,354 @@ function scriptsMd(scripts) {
 
 function hideOnWindows(dirPath) {
   if (process.platform === 'win32') {
-    try { require('child_process').execSync(`attrib +h "${dirPath}"`, { stdio: 'ignore' }); } catch {}
+    try { require('child_process').execFileSync('attrib', ['+h', dirPath], { stdio: 'ignore' }); } catch {}
   }
 }
-
-function chmodExecutable(filePath) {
-  try { fs.chmodSync(filePath, 0o755); } catch {}
-}
-
-function ensure(filePath, content) {
-  if (fs.existsSync(filePath)) return false;
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content, 'utf8');
+
+function chmodExecutable(filePath) {
+  try { fs.chmodSync(filePath, 0o755); } catch {}
+}
+
+function ensure(filePath, content) {
+  if (fs.existsSync(filePath)) return false;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
   return true;
 }
 
-function write(filePath, content) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content, 'utf8');
-}
-
-function tplMemocCmdWrapper(cliPath = runtimeCliPath()) {
-  return `@echo off\r\nnode "${escapeCmdPath(cliPath)}" %*\r\n`;
-}
-
-function tplMemocPs1Wrapper(cliPath = runtimeCliPath()) {
-  return `& node ${psSingleQuote(cliPath)} @args\nexit $LASTEXITCODE\n`;
-}
-
-function tplMemocShWrapper(cliPath = runtimeCliPath()) {
-  return `#!/bin/sh\nexec node ${shellSingleQuote(cliPath)} "$@"\n`;
-}
-
-function defaultUserBinDir() {
-  if (process.env.MEMOC_USER_BIN_DIR) return process.env.MEMOC_USER_BIN_DIR;
-  if (currentPlatform() === 'win32') {
-    return path.join(process.env.LOCALAPPDATA || path.join(process.env.USERPROFILE || process.cwd(), 'AppData', 'Local'), 'memoc', 'bin');
-  }
-  return path.join(process.env.HOME || process.cwd(), '.local', 'bin');
-}
-
-function defaultRuntimeDir() {
-  if (process.env.MEMOC_RUNTIME_DIR) return process.env.MEMOC_RUNTIME_DIR;
-  if (currentPlatform() === 'win32') {
-    return path.join(process.env.LOCALAPPDATA || path.join(process.env.USERPROFILE || process.cwd(), 'AppData', 'Local'), 'memoc', 'runtime');
-  }
-  return path.join(process.env.HOME || process.cwd(), '.local', 'share', 'memoc', 'runtime');
-}
-
-function runtimeCliPath() {
-  return path.join(defaultRuntimeDir(), 'bin', 'cli.js');
-}
-
-function tplEnvPs1() {
-  return `$memocBin = Join-Path $PSScriptRoot 'bin'\n$parts = $env:PATH -split [IO.Path]::PathSeparator\nif ($parts -notcontains $memocBin) {\n  $env:PATH = \"$memocBin$([IO.Path]::PathSeparator)$env:PATH\"\n}\n`;
-}
-
+function write(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function tplMemocCmdWrapper(cliPath = runtimeCliPath()) {
+  return `@echo off\r\nnode "${escapeCmdPath(cliPath)}" %*\r\n`;
+}
+
+function tplMemocPs1Wrapper(cliPath = runtimeCliPath()) {
+  return `& node ${psSingleQuote(cliPath)} @args\nexit $LASTEXITCODE\n`;
+}
+
+function tplMemocShWrapper(cliPath = runtimeCliPath()) {
+  return `#!/bin/sh\nexec node ${shellSingleQuote(cliPath)} "$@"\n`;
+}
+
+function defaultUserBinDir() {
+  if (process.env.MEMOC_USER_BIN_DIR) return process.env.MEMOC_USER_BIN_DIR;
+  if (currentPlatform() === 'win32') {
+    return path.join(process.env.LOCALAPPDATA || path.join(process.env.USERPROFILE || process.cwd(), 'AppData', 'Local'), 'memoc', 'bin');
+  }
+  return path.join(process.env.HOME || process.cwd(), '.local', 'bin');
+}
+
+function defaultRuntimeDir() {
+  if (process.env.MEMOC_RUNTIME_DIR) return process.env.MEMOC_RUNTIME_DIR;
+  if (currentPlatform() === 'win32') {
+    return path.join(process.env.LOCALAPPDATA || path.join(process.env.USERPROFILE || process.cwd(), 'AppData', 'Local'), 'memoc', 'runtime');
+  }
+  return path.join(process.env.HOME || process.cwd(), '.local', 'share', 'memoc', 'runtime');
+}
+
+function runtimeCliPath() {
+  return path.join(defaultRuntimeDir(), 'bin', 'cli.js');
+}
+
+function tplEnvPs1() {
+  return `$memocBin = Join-Path $PSScriptRoot 'bin'\n$parts = $env:PATH -split [IO.Path]::PathSeparator\nif ($parts -notcontains $memocBin) {\n  $env:PATH = \"$memocBin$([IO.Path]::PathSeparator)$env:PATH\"\n}\n`;
+}
+
 function tplEnvSh() {
-  return `# Source this from the project root to put the local memoc wrapper first in PATH.\nMEMOC_DIR="$(pwd)/.memoc"\ncase ":$PATH:" in\n  *":$MEMOC_DIR/bin:"*) ;;\n  *) PATH="$MEMOC_DIR/bin:$PATH"; export PATH ;;\nesac\n`;
-}
-
-function ensurePathHelpers(dir, mark) {
-  const cliPath = ensureRuntimeInstall(mark);
-  const files = [
-    [path.join(dir, '.memoc', 'bin', 'memoc.cmd'), () => tplMemocCmdWrapper(cliPath), false],
-    [path.join(dir, '.memoc', 'bin', 'memoc.ps1'), () => tplMemocPs1Wrapper(cliPath), false],
-    [path.join(dir, '.memoc', 'bin', 'memoc'), () => tplMemocShWrapper(cliPath), true],
-    [path.join(dir, '.memoc', 'env.ps1'), tplEnvPs1, false],
-    [path.join(dir, '.memoc', 'env.sh'), tplEnvSh, true],
-  ];
-
-  for (const [fp, tpl, executable] of files) {
-    const rel = path.relative(dir, fp);
-    const added = writeIfChanged(fp, tpl());
-    if (executable) chmodExecutable(fp);
-    mark(added, rel);
-  }
+  return `# Source this from the project root to put the local memoc wrapper first in PATH.\nMEMOC_DIR="$PWD/.memoc"\ncase ":$PATH:" in\n  *":$MEMOC_DIR/bin:"*) ;;\n  *) PATH="$MEMOC_DIR/bin:$PATH"; export PATH ;;\nesac\n`;
 }
-
-function ensureUserLauncher(mark) {
-  const userBin = defaultUserBinDir();
-  writeLaunchers(userBin, mark, 'user bin', ensureRuntimeInstall(mark));
-  return userBin;
-}
-
-function writeLaunchers(binDir, mark, label, cliPath = ensureRuntimeInstall(mark)) {
-  const files = [
-    [path.join(binDir, 'memoc.cmd'), () => tplMemocCmdWrapper(cliPath), false],
-    [path.join(binDir, 'memoc.ps1'), () => tplMemocPs1Wrapper(cliPath), false],
-    [path.join(binDir, 'memoc'), () => tplMemocShWrapper(cliPath), true],
-  ];
-
-  for (const [fp, tpl, executable] of files) {
-    const added = writeIfChanged(fp, tpl());
-    if (executable) chmodExecutable(fp);
-    mark(added, `${label} ${path.basename(fp)}`);
-  }
-}
-
-function writeIfChanged(filePath, content) {
-  if (!fs.existsSync(filePath)) {
-    write(filePath, content);
-    return 'add';
-  }
-  try {
-    if (fs.readFileSync(filePath, 'utf8') === content) return 'skip';
-  } catch {}
-  write(filePath, content);
-  return 'update';
-}
-
-function ensurePathRegistration(dir, mark) {
-  ensureCurrentPathLauncher(mark);
-  const binDir = ensureUserLauncher(mark);
-  const pathSep = path.delimiter;
-
-  if ((process.env.PATH || '').split(pathSep).some(p => samePath(p, binDir))) {
-    mark('skip', 'PATH (user memoc bin already active)');
-    return;
-  }
-
-  process.env.PATH = `${binDir}${pathSep}${process.env.PATH || ''}`;
-
-  if (process.env.MEMOC_SKIP_PATH_REGISTER === '1') {
-    mark('skip', 'PATH registration (test mode)');
-    return;
-  }
-
-  if (currentPlatform() !== 'win32') {
-    const updated = ensureUnixPathRegistration(binDir);
-    mark(updated ? 'update' : 'skip', `${currentPlatform()} PATH (${userPathShellHint(binDir)})`);
-    return;
-  }
-
-  try {
-    const current = require('child_process')
-      .execFileSync('powershell.exe', [
-        '-NoProfile',
-        '-ExecutionPolicy', 'Bypass',
-        '-Command',
-        "[Environment]::GetEnvironmentVariable('Path','User')",
-      ], { encoding: 'utf8' })
-      .trim();
-    const parts = current.split(pathSep).filter(Boolean);
-    if (parts.some(p => samePath(p, binDir))) {
-      mark('skip', 'User PATH (memoc bin already registered)');
-      return;
-    }
-    const nextPath = [binDir, ...parts].join(pathSep);
-    require('child_process').execFileSync('powershell.exe', [
-      '-NoProfile',
-      '-ExecutionPolicy', 'Bypass',
-      '-Command',
-      `[Environment]::SetEnvironmentVariable('Path', ${JSON.stringify(nextPath)}, 'User')`,
-    ], { stdio: 'ignore' });
-    mark('update', 'User PATH (memoc bin added; open a new terminal if needed)');
-  } catch {
-    mark('skip', 'User PATH registration failed (use . .\\.memoc\\env.ps1)');
-  }
-}
-
-function ensureCurrentPathLauncher(mark) {
-  const target = findWritablePathDir();
-  if (!target) {
-    mark('skip', 'active PATH launcher (no writable PATH directory found)');
-    return false;
-  }
-  writeLaunchers(target, mark, 'active PATH', ensureRuntimeInstall(mark));
-  return true;
-}
-
-function ensureRuntimeInstall(mark) {
-  const runtimeDir = defaultRuntimeDir();
-  const sourceRoot = path.join(__dirname, '..');
-  const files = [
-    [path.join(sourceRoot, 'bin', 'cli.js'), path.join(runtimeDir, 'bin', 'cli.js')],
-    [path.join(sourceRoot, 'package.json'), path.join(runtimeDir, 'package.json')],
-  ];
-
-  for (const [src, dest] of files) {
-    try {
-      const content = fs.readFileSync(src, 'utf8');
-      const changed = writeIfChanged(dest, content);
-      mark(changed, `runtime ${path.relative(runtimeDir, dest)}`);
-    } catch {
-      mark('skip', `runtime ${path.basename(dest)} unavailable`);
-    }
-  }
-
-  chmodExecutable(path.join(runtimeDir, 'bin', 'cli.js'));
-  return path.join(runtimeDir, 'bin', 'cli.js');
-}
-
-function findWritablePathDir() {
-  const dirs = [...new Set((process.env.PATH || '').split(path.delimiter).filter(Boolean))];
-  const npmBin = npmGlobalBinDir();
-  const ranked = dirs
-    .filter(d => !isVolatilePathDir(d))
-    .filter(d => {
-      try { return fs.existsSync(d) && fs.statSync(d).isDirectory() && canWriteDir(d); }
-      catch { return false; }
-    })
-    .sort((a, b) => pathRank(a, npmBin) - pathRank(b, npmBin));
-  return ranked[0] || null;
-}
-
-function pathRank(dir, npmBin) {
-  if (npmBin && samePath(dir, npmBin)) return 0;
-  const lower = dir.toLowerCase();
-  for (const root of userWritableRoots()) {
-    if (root && lower.startsWith(root.toLowerCase())) return 1;
-  }
-  return 5;
-}
-
-function userWritableRoots() {
-  return [
-    process.env.APPDATA,
-    process.env.LOCALAPPDATA,
-    process.env.HOME,
-    process.env.USERPROFILE,
-  ].filter(Boolean).map(p => path.resolve(p));
-}
-
-function npmGlobalBinDir() {
-  try {
-    const prefix = require('child_process').execFileSync('npm', ['config', 'get', 'prefix'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    if (!prefix) return null;
-    return currentPlatform() === 'win32' ? prefix : path.join(prefix, 'bin');
-  } catch {
-    return null;
-  }
-}
-
-function isVolatilePathDir(dir) {
-  const lower = dir.toLowerCase();
-  return lower.includes(`${path.sep}_npx${path.sep}`) ||
-    lower.includes(`${path.sep}node_modules${path.sep}.bin`) ||
-    lower.includes(`${path.sep}npm-cache${path.sep}_npx${path.sep}`);
-}
-
-function canWriteDir(dir) {
-  const probe = path.join(dir, `.memoc-write-test-${process.pid}-${Date.now()}`);
-  try {
-    fs.writeFileSync(probe, '');
-    fs.unlinkSync(probe);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function ensureUnixPathRegistration(binDir) {
-  if (process.env.MEMOC_SKIP_PATH_REGISTER === '1') return false;
-
-  const home = process.env.HOME;
-  if (!home) return false;
-
-  const block = [
-    '# memoc PATH',
-    `MEMOC_BIN=${shellSingleQuote(binDir)}`,
-    'case ":$PATH:" in *":$MEMOC_BIN:"*) ;; *) PATH="$MEMOC_BIN:$PATH"; export PATH ;; esac',
-    '# end memoc PATH',
-  ].join('\n');
-
-  const candidates = [
-    path.join(home, '.profile'),
-    path.join(home, '.zshrc'),
-    path.join(home, '.bashrc'),
-  ];
-
-  let changed = false;
-  for (const fp of candidates) {
-    try {
-      const src = fs.existsSync(fp) ? fs.readFileSync(fp, 'utf8') : '';
-      if (src.includes(binDir) || src.includes('# memoc PATH')) continue;
-      fs.appendFileSync(fp, `${src.endsWith('\n') || !src ? '' : '\n'}\n${block}\n`, 'utf8');
-      changed = true;
-    } catch {}
-  }
-  return changed;
-}
-
-function userPathShellHint(binDir) {
-  return `user bin ${binDir} ${process.env.MEMOC_SKIP_PATH_REGISTER === '1' ? 'test mode' : 'registered; open a new terminal if needed'}`;
-}
-
-function currentPlatform() {
-  return process.env.MEMOC_PLATFORM || process.platform;
-}
-
-function shellSingleQuote(value) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
-
-function psSingleQuote(value) {
-  return `'${String(value).replace(/'/g, "''")}'`;
-}
-
-function escapeCmdPath(value) {
-  return String(value).replace(/"/g, '""');
-}
-
-function samePath(a, b) {
-  if (!a || !b) return false;
-  const norm = p => path.resolve(p).toLowerCase().replace(/[\\/]+$/, '');
-  try { return norm(a) === norm(b); } catch { return false; }
-}
-
+
+function ensurePathHelpers(dir, mark) {
+  const cliPath = ensureRuntimeInstall(mark);
+  const files = [
+    [path.join(dir, '.memoc', 'bin', 'memoc.cmd'), () => tplMemocCmdWrapper(cliPath), false],
+    [path.join(dir, '.memoc', 'bin', 'memoc.ps1'), () => tplMemocPs1Wrapper(cliPath), false],
+    [path.join(dir, '.memoc', 'bin', 'memoc'), () => tplMemocShWrapper(cliPath), true],
+    [path.join(dir, '.memoc', 'env.ps1'), tplEnvPs1, false],
+    [path.join(dir, '.memoc', 'env.sh'), tplEnvSh, true],
+  ];
+
+  for (const [fp, tpl, executable] of files) {
+    const rel = path.relative(dir, fp);
+    const added = writeIfChanged(fp, tpl());
+    if (executable) chmodExecutable(fp);
+    mark(added, rel);
+  }
+}
+
+function ensureUserLauncher(mark) {
+  const userBin = defaultUserBinDir();
+  writeLaunchers(userBin, mark, 'user bin', ensureRuntimeInstall(mark));
+  return userBin;
+}
+
+function writeLaunchers(binDir, mark, label, cliPath = ensureRuntimeInstall(mark)) {
+  const files = [
+    [path.join(binDir, 'memoc.cmd'), () => tplMemocCmdWrapper(cliPath), false],
+    [path.join(binDir, 'memoc.ps1'), () => tplMemocPs1Wrapper(cliPath), false],
+    [path.join(binDir, 'memoc'), () => tplMemocShWrapper(cliPath), true],
+  ];
+
+  for (const [fp, tpl, executable] of files) {
+    const added = writeIfChanged(fp, tpl());
+    if (executable) chmodExecutable(fp);
+    mark(added, `${label} ${path.basename(fp)}`);
+  }
+}
+
+function writeIfChanged(filePath, content) {
+  if (!fs.existsSync(filePath)) {
+    write(filePath, content);
+    return 'add';
+  }
+  try {
+    if (fs.readFileSync(filePath, 'utf8') === content) return 'skip';
+  } catch {}
+  write(filePath, content);
+  return 'update';
+}
+
+function ensurePathRegistration(dir, mark) {
+  ensureCurrentPathLauncher(mark);
+  const binDir = ensureUserLauncher(mark);
+  const pathSep = path.delimiter;
+
+  if ((process.env.PATH || '').split(pathSep).some(p => samePath(p, binDir))) {
+    mark('skip', 'PATH (user memoc bin already active)');
+    return;
+  }
+
+  process.env.PATH = `${binDir}${pathSep}${process.env.PATH || ''}`;
+
+  if (process.env.MEMOC_SKIP_PATH_REGISTER === '1') {
+    mark('skip', 'PATH registration (test mode)');
+    return;
+  }
+
+  if (currentPlatform() !== 'win32') {
+    const updated = ensureUnixPathRegistration(binDir);
+    mark(updated ? 'update' : 'skip', `${currentPlatform()} PATH (${userPathShellHint(binDir)})`);
+    return;
+  }
+
+  try {
+    const current = require('child_process')
+      .execFileSync('powershell.exe', [
+        '-NoProfile',
+        '-ExecutionPolicy', 'Bypass',
+        '-Command',
+        "[Environment]::GetEnvironmentVariable('Path','User')",
+      ], { encoding: 'utf8' })
+      .trim();
+    const parts = current.split(pathSep).filter(Boolean);
+    if (parts.some(p => samePath(p, binDir))) {
+      mark('skip', 'User PATH (memoc bin already registered)');
+      return;
+    }
+    const nextPath = [binDir, ...parts].join(pathSep);
+    require('child_process').execFileSync('powershell.exe', [
+      '-NoProfile',
+      '-ExecutionPolicy', 'Bypass',
+      '-Command',
+      `[Environment]::SetEnvironmentVariable('Path', ${JSON.stringify(nextPath)}, 'User')`,
+    ], { stdio: 'ignore' });
+    mark('update', 'User PATH (memoc bin added; open a new terminal if needed)');
+  } catch {
+    mark('skip', 'User PATH registration failed (use . .\\.memoc\\env.ps1)');
+  }
+}
+
+function ensureCurrentPathLauncher(mark) {
+  const target = findWritablePathDir();
+  if (!target) {
+    mark('skip', 'active PATH launcher (no writable PATH directory found)');
+    return false;
+  }
+  writeLaunchers(target, mark, 'active PATH', ensureRuntimeInstall(mark));
+  return true;
+}
+
+function ensureRuntimeInstall(mark) {
+  const runtimeDir = defaultRuntimeDir();
+  const sourceRoot = path.join(__dirname, '..');
+  const files = [
+    [path.join(sourceRoot, 'bin', 'cli.js'), path.join(runtimeDir, 'bin', 'cli.js')],
+    [path.join(sourceRoot, 'package.json'), path.join(runtimeDir, 'package.json')],
+  ];
+
+  for (const [src, dest] of files) {
+    try {
+      const content = fs.readFileSync(src, 'utf8');
+      const changed = writeIfChanged(dest, content);
+      mark(changed, `runtime ${path.relative(runtimeDir, dest)}`);
+    } catch {
+      mark('skip', `runtime ${path.basename(dest)} unavailable`);
+    }
+  }
+
+  chmodExecutable(path.join(runtimeDir, 'bin', 'cli.js'));
+  return path.join(runtimeDir, 'bin', 'cli.js');
+}
+
+function findWritablePathDir() {
+  const dirs = [...new Set((process.env.PATH || '').split(path.delimiter).filter(Boolean))];
+  const npmBin = npmGlobalBinDir();
+  const ranked = dirs
+    .filter(d => !isVolatilePathDir(d))
+    .filter(d => {
+      try { return fs.existsSync(d) && fs.statSync(d).isDirectory() && canWriteDir(d); }
+      catch { return false; }
+    })
+    .sort((a, b) => pathRank(a, npmBin) - pathRank(b, npmBin));
+  return ranked[0] || null;
+}
+
+function pathRank(dir, npmBin) {
+  if (npmBin && samePath(dir, npmBin)) return 0;
+  const lower = dir.toLowerCase();
+  for (const root of userWritableRoots()) {
+    if (root && lower.startsWith(root.toLowerCase())) return 1;
+  }
+  return 5;
+}
+
+function userWritableRoots() {
+  return [
+    process.env.APPDATA,
+    process.env.LOCALAPPDATA,
+    process.env.HOME,
+    process.env.USERPROFILE,
+  ].filter(Boolean).map(p => path.resolve(p));
+}
+
+function npmGlobalBinDir() {
+  try {
+    const prefix = require('child_process').execFileSync('npm', ['config', 'get', 'prefix'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (!prefix) return null;
+    return currentPlatform() === 'win32' ? prefix : path.join(prefix, 'bin');
+  } catch {
+    return null;
+  }
+}
+
+function isVolatilePathDir(dir) {
+  const lower = dir.toLowerCase();
+  return lower.includes(`${path.sep}_npx${path.sep}`) ||
+    lower.includes(`${path.sep}node_modules${path.sep}.bin`) ||
+    lower.includes(`${path.sep}npm-cache${path.sep}_npx${path.sep}`);
+}
+
+function canWriteDir(dir) {
+  const probe = path.join(dir, `.memoc-write-test-${process.pid}-${Date.now()}`);
+  try {
+    fs.writeFileSync(probe, '');
+    fs.unlinkSync(probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ensureUnixPathRegistration(binDir) {
+  if (process.env.MEMOC_SKIP_PATH_REGISTER === '1') return false;
+
+  const home = process.env.HOME;
+  if (!home) return false;
+
+  const block = [
+    '# memoc PATH',
+    `MEMOC_BIN=${shellSingleQuote(binDir)}`,
+    'case ":$PATH:" in *":$MEMOC_BIN:"*) ;; *) PATH="$MEMOC_BIN:$PATH"; export PATH ;; esac',
+    '# end memoc PATH',
+  ].join('\n');
+
+  const candidates = [
+    path.join(home, '.profile'),
+    path.join(home, '.zshrc'),
+    path.join(home, '.bashrc'),
+  ];
+
+  let changed = false;
+  for (const fp of candidates) {
+    try {
+      const src = fs.existsSync(fp) ? fs.readFileSync(fp, 'utf8') : '';
+      if (src.includes(binDir) || src.includes('# memoc PATH')) continue;
+      fs.appendFileSync(fp, `${src.endsWith('\n') || !src ? '' : '\n'}\n${block}\n`, 'utf8');
+      changed = true;
+    } catch {}
+  }
+  return changed;
+}
+
+function userPathShellHint(binDir) {
+  return `user bin ${binDir} ${process.env.MEMOC_SKIP_PATH_REGISTER === '1' ? 'test mode' : 'registered; open a new terminal if needed'}`;
+}
+
+function currentPlatform() {
+  return process.env.MEMOC_PLATFORM || process.platform;
+}
+
+function shellSingleQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function psSingleQuote(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function escapeCmdPath(value) {
+  return String(value).replace(/"/g, '""');
+}
+
+function samePath(a, b) {
+  if (!a || !b) return false;
+  const norm = p => path.resolve(p).toLowerCase().replace(/[\\/]+$/, '');
+  try { return norm(a) === norm(b); } catch { return false; }
+}
+
 function updateSection(filePath, startMark, endMark, inner) {
   if (!fs.existsSync(filePath)) return false;
   const src = fs.readFileSync(filePath, 'utf8');
-  const s = src.indexOf(startMark);
-  const e = src.indexOf(endMark);
-  if (s === -1 || e === -1) return false;
-  write(filePath,
-    src.slice(0, s) + startMark + '\n' + inner + '\n' + endMark + src.slice(e + endMark.length)
-  );
-  return true;
-}
+  const range = findMarkedRange(src, startMark, endMark);
+  if (!range) return false;
+  write(filePath,
+    src.slice(0, range.s) + startMark + '\n' + inner + '\n' + endMark + src.slice(range.e + range.endMark.length)
+  );
+  return true;
+}
 
 // ═══════════════════════════════════════════════════════════════════
 // SECTION MARKERS
 // ═══════════════════════════════════════════════════════════════════
 
-const mk = n => [`<!-- context-forge:${n}:start -->`, `<!-- context-forge:${n}:end -->`];
-const [MGMT_S,  MGMT_E]  = mk('managed');
-const [ID_S,    ID_E]    = mk('identity');
-const [SNAP_S,  SNAP_E]  = mk('snapshot');
-const [CORE_S,  CORE_E]  = mk('core');
-const [HDR_S,   HDR_E]   = mk('header');
-const [SYS_S,   SYS_E]   = mk('systems');
-const [WIKI_S,  WIKI_E]  = mk('wiki');
+const mk = n => [`<!-- memoc:${n}:start -->`, `<!-- memoc:${n}:end -->`];
+const [MGMT_S,  MGMT_E]  = mk('managed');
+const [ID_S,    ID_E]    = mk('identity');
+const [SNAP_S,  SNAP_E]  = mk('snapshot');
+const [CORE_S,  CORE_E]  = mk('core');
+const [HDR_S,   HDR_E]   = mk('header');
+const [SYS_S,   SYS_E]   = mk('systems');
+const [WIKI_S,  WIKI_E]  = mk('wiki');
+
+function markerPairs(startMark, endMark) {
+  const legacyStart = startMark.replace('<!-- memoc:', '<!-- context-forge:');
+  const legacyEnd = endMark.replace('<!-- memoc:', '<!-- context-forge:');
+  return legacyStart === startMark
+    ? [[startMark, endMark]]
+    : [[startMark, endMark], [legacyStart, legacyEnd]];
+}
+
+function findMarkedRange(src, startMark, endMark) {
+  for (const [sMark, eMark] of markerPairs(startMark, endMark)) {
+    const s = src.indexOf(sMark);
+    const e = src.indexOf(eMark);
+    if (s !== -1 && e !== -1 && e > s) return { s, e, endMark: eMark };
+  }
+  return null;
+}
 
 // ═══════════════════════════════════════════════════════════════════
 // AGENT REGISTRY — third-party agent entry files (added via `add`)
@@ -536,18 +552,18 @@ const AGENT_REGISTRY = {
 // DYNAMIC CONTENT (re-generated on update)
 // ═══════════════════════════════════════════════════════════════════
 
-function managedBlock() {
+function legacyManagedBlock() {
   return `${MGMT_S}
-## Session Start
-- [ ] Read \`.memoc/session-summary.md\`
-- [ ] \`.pending\` exists? → review changed files → update memory if needed → delete it
-- [ ] If \`memoc\` is not found in an existing shell, open a new terminal or load the local helper: PowerShell \`. .\\.memoc\\env.ps1\`; sh \`. ./.memoc/env.sh\`
-
-## Before Opening More Files
-- [ ] Run memoc commands in this order: \`memoc search "<query>"\` → \`.\\.memoc\\bin\\memoc.cmd search "<query>"\` (Windows) or \`.memoc/bin/memoc search "<query>"\` (sh) → \`npx @kevin0181/memoc search "<query>"\`
-- [ ] Open on demand: \`02\` status · \`04\` resume · \`06\` rules · \`llms.txt\` map
-- [ ] If memory search is not enough, search project files with \`memoc grep "<query>" --limit 5\`
-- [ ] Keep output small: \`summary\`, \`search --limit\`, \`grep --limit\`, \`--snippets\`
+## Session Start
+- [ ] Read \`.memoc/session-summary.md\`
+- [ ] \`.pending\` exists? → review changed files → update memory if needed → delete it
+- [ ] If \`memoc\` is not found in an existing shell, open a new terminal or load the local helper: PowerShell \`. .\\.memoc\\env.ps1\`; sh \`. ./.memoc/env.sh\`
+
+## Before Opening More Files
+- [ ] Run memoc commands in this order: \`memoc search "<query>"\` → \`.\\.memoc\\bin\\memoc.cmd search "<query>"\` (Windows) or \`.memoc/bin/memoc search "<query>"\` (sh) → \`npx @kevin0181/memoc search "<query>"\`
+- [ ] Open on demand: \`02\` status · \`04\` resume · \`06\` rules · \`llms.txt\` map
+- [ ] If memory search is not enough, search project files with \`memoc grep "<query>" --limit 5\`
+- [ ] Keep output small: \`summary\`, \`search --limit\`, \`grep --limit\`, \`--snippets\`
 
 ## Before Finishing _(update only applicable files; skip Q&A / throwaway exploration)_
 - [ ] Code/config/deps changed → \`02\` (version, commands list, Last synced) + \`session-summary.md\` (status, changed, open tasks)
@@ -558,7 +574,29 @@ function managedBlock() {
 ${MGMT_E}`;
 }
 
-function identityInner(p) {
+function managedBlock() {
+  return `${MGMT_S}
+## Session Start
+- [ ] Read \`.memoc/session-summary.md\`
+- [ ] \`.pending\` exists? Review changed files, update memory if needed, then delete it.
+- [ ] If \`memoc\` is not found, use the project-local wrapper for the rest of the session: Windows \`.\\.memoc\\bin\\memoc.cmd <command>\`; sh \`.memoc/bin/memoc <command>\`
+
+## Before Opening More Files
+- [ ] Search memory first: \`memoc search "<query>" --limit 5\`, or wrapper fallback above if PATH fails
+- [ ] Open on demand: \`02\` status, \`04\` resume, \`06\` rules, \`llms.txt\` map
+- [ ] If memory search is not enough, search project files with \`memoc grep "<query>" --limit 5\` (or wrapper fallback)
+- [ ] Keep output small: \`summary\`, \`search --limit\`, \`grep --limit\`, \`--snippets\`
+
+## Before Finishing _(update only applicable files; skip Q&A / throwaway exploration)_
+- [ ] Code/config/deps changed? Update \`02\` + \`session-summary.md\`
+- [ ] Decision made? Update \`03-decisions.md\` + \`02\`
+- [ ] Work incomplete or risky? Update \`04-handoff.md\`
+- [ ] Rule/preference set? Update \`06-project-rules.md\`
+- [ ] Wiki/systems work? Read \`skills/project-memory-maintainer/SKILL.md\`
+${MGMT_E}`;
+}
+
+function identityInner(p) {
   return [
     `- Project name: \`${p.name}\``,
     `- Detected stack: ${stackStr(p.stack)}`,
@@ -858,14 +896,14 @@ On-demand reference only. The entry-file managed block is authoritative.
 | \`.memoc/wiki/*.md\` | For synthesized project knowledge |
 | \`llms.txt\` | For full project file map |
 
-## Search First
-
-\`memoc search "<query>"\` — returns file:line matches across memory and agent docs only.
-\`memoc grep "<query>"\` — searches project source/text files when memory docs are not enough.
-If \`memoc\` is not on PATH, try \`.\\.memoc\\bin\\memoc.cmd search "<query>"\` on Windows or \`.memoc/bin/memoc search "<query>"\` in sh, then \`npx @kevin0181/memoc search "<query>"\`.
-Use it before opening any file to avoid reading more than needed.
-`;
-}
+## Search First
+
+\`memoc search "<query>"\` — returns file:line matches across memory and agent docs only.
+\`memoc grep "<query>"\` — searches project source/text files when memory docs are not enough.
+If \`memoc\` is not on PATH, try \`.\\.memoc\\bin\\memoc.cmd search "<query>"\` on Windows or \`.memoc/bin/memoc search "<query>"\` in sh, then \`npx @kevin0181/memoc search "<query>"\`.
+Use it before opening any file to avoid reading more than needed.
+`;
+}
 
 function tplWorkflow() {
   return `# Agent Workflow
@@ -1020,20 +1058,23 @@ Append-only chronological log for project memory updates.
 `;
 }
 
-function tplContextForgeUsage() {
-  return `# memoc Usage
+function tplMemocUsage() {
+  return `# memoc Usage
 
 This project uses \`memoc\` to maintain agent-readable project memory.
 
-## Commands
-
-\`\`\`bash
-# Optional: put the project-local wrapper first in PATH for this shell
-# PowerShell: . .\\.memoc\\env.ps1
-# sh/bash:    . ./.memoc/env.sh
-
-# First-time setup (or re-run to update managed sections)
-memoc init
+## Commands
+
+\`\`\`bash
+# Optional: put the project-local wrapper first in PATH for this shell
+# PowerShell: . .\\.memoc\\env.ps1
+# sh/bash:    . ./.memoc/env.sh
+
+# First-time setup (or re-run to update managed sections)
+memoc init
+
+# Refresh memoc itself when run through npx @latest, preserving project memory
+memoc upgrade
 
 # Explicitly update managed sections based on current project state
 memoc update
@@ -1041,24 +1082,27 @@ memoc update
 # Tiny status overview
 memoc summary
 
-# Search memory first; add --snippets only when needed
-memoc search "<query>" --limit 12
-memoc search "<query>" --snippets --limit 5
-
-# Search project source/text files when memory is not enough
-memoc grep "<query>" --limit 12
-memoc grep "<query>" --snippets --limit 5
-\`\`\`
-
-If \`memoc\` is not on PATH, use \`.\\.memoc\\bin\\memoc.cmd <command>\` on Windows or \`.memoc/bin/memoc <command>\` in sh. If that is unavailable, use \`npx @kevin0181/memoc <command>\`.
-
+# Search memory first; add --snippets only when needed
+memoc search "<query>" --limit 12
+memoc search "<query>" --snippets --limit 5
+
+# Search project source/text files when memory is not enough
+memoc grep "<query>" --limit 12
+memoc grep "<query>" --snippets --limit 5
+\`\`\`
+
+If \`memoc\` is not on PATH, use \`.\\.memoc\\bin\\memoc.cmd <command>\` on Windows or \`.memoc/bin/memoc <command>\` in sh for the rest of the session. If the local wrapper is missing, use \`npx @kevin0181/memoc <command>\` or re-run init.
+
 ## Agent Read Order
 
 1. Entry-file managed block.
 2. \`.memoc/session-summary.md\` only.
-3. Search memory first: \`memoc search "<query>"\`.
-4. If memory is not enough, search project files: \`memoc grep "<query>" --limit 5\`.
-5. Use \`--snippets\` only when file names are not enough.
+3. Search memory first with one or two concrete terms: \`memoc search "<query>" --limit 5\`.
+4. Open only the matching memory file(s) that matter.
+5. If memory is not enough, search project files: \`memoc grep "<query>" --limit 5\`.
+6. Use \`--snippets\` only when file names are not enough.
+
+Use \`memoc search\` for known concepts, changed areas, decisions, tasks, or handoff notes. Skip it for brand-new questions where no prior memory can exist.
 
 ## When To Run Memory Updates
 
@@ -1149,11 +1193,11 @@ description: Maintain this project's LLM-wiki memory files after durable context
 
 Use this local skill after meaningful project work so future agents can continue without rediscovering context.
 
-## Required Reads
-
-1. \`.memoc/session-summary.md\`
-2. \`memoc summary\` or \`memoc search "<query>"\`; use \`memoc grep "<query>"\` only when source/text search is needed
-3. Open only files you will use or update.
+## Required Reads
+
+1. \`.memoc/session-summary.md\`
+2. \`memoc summary\` or \`memoc search "<query>"\`; use \`memoc grep "<query>"\` only when source/text search is needed
+3. Open only files you will use or update.
 
 ## Maintenance Checklist
 
@@ -1188,9 +1232,9 @@ Usually skip for pure Q&A, tiny edits with no future impact, or throwaway explor
 // CLAUDE CODE HOOK SETTINGS
 // ═══════════════════════════════════════════════════════════════════
 
-function claudeStopHookCmd() {
-  return `node -e "const fs=require('fs'),{execSync}=require('child_process');try{const o=execSync('git status --porcelain',{stdio:'pipe'}).toString();if(o.trim()){const files=o.trim().split('\\n').map(l=>l.slice(3).trim()).filter(Boolean).slice(0,8).join(', ');fs.writeFileSync('.memoc/.pending',new Date().toISOString()+'\\n'+files)}}catch{}" 2>/dev/null || true`;
-}
+function claudeStopHookCmd() {
+  return `node -e "const fs=require('fs'),{execFileSync}=require('child_process');try{const o=execFileSync('git',['status','--porcelain'],{encoding:'utf8',stdio:['ignore','pipe','ignore']});if(o.trim()){const files=o.trim().split(/\\r?\\n/).map(l=>l.slice(3).trim()).filter(Boolean).slice(0,8).join(', ');fs.writeFileSync('.memoc/.pending',new Date().toISOString()+'\\n'+files)}}catch{}"`;
+}
 
 function tplClaudeSettings() {
   return JSON.stringify({
@@ -1200,43 +1244,108 @@ function tplClaudeSettings() {
   }, null, 2) + '\n';
 }
 
-function ensureClaudeStopHook(settingsPath) {
-  const cmd = claudeStopHookCmd();
-  let settings;
-  try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); }
-  catch { settings = {}; }
+function ensureClaudeStopHook(settingsPath) {
+  const cmd = claudeStopHookCmd();
+  let settings;
+  try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); }
+  catch { settings = {}; }
 
-  if (!settings.hooks) settings.hooks = {};
-  if (!settings.hooks.Stop) settings.hooks.Stop = [];
+  if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
 
-  const alreadyPresent = settings.hooks.Stop.some(entry =>
-    Array.isArray(entry.hooks) && entry.hooks.some(h => h.command === cmd)
-  );
-  if (alreadyPresent) return false; // no change needed
-
-  settings.hooks.Stop.push({ matcher: '', hooks: [{ type: 'command', command: cmd }] });
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-  return true; // merged
-}
+  let hasCurrent = false;
+  let changed = false;
+  for (const entry of settings.hooks.Stop) {
+    if (!Array.isArray(entry.hooks)) continue;
+    const nextHooks = [];
+    for (const hook of entry.hooks) {
+      if (hook && hook.command === cmd) {
+        if (hasCurrent) changed = true;
+        else {
+          hasCurrent = true;
+          nextHooks.push(hook);
+        }
+      } else if (isMemocClaudeStopHook(hook)) {
+        changed = true;
+      } else {
+        nextHooks.push(hook);
+      }
+    }
+    entry.hooks = nextHooks;
+  }
+  settings.hooks.Stop = settings.hooks.Stop.filter(entry =>
+    !Array.isArray(entry.hooks) || entry.hooks.length > 0
+  );
+  if (hasCurrent && !changed) return false; // no change needed
+
+  if (!hasCurrent) settings.hooks.Stop.push({ matcher: '', hooks: [{ type: 'command', command: cmd }] });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  return true; // merged or migrated
+}
+
+function isMemocClaudeStopHook(hook) {
+  if (!hook || typeof hook.command !== 'string') return false;
+  const command = hook.command;
+  return command.includes('.memoc/.pending') &&
+    command.includes('git') &&
+    command.includes('status') &&
+    command.includes('--porcelain');
+}
 
 // ═══════════════════════════════════════════════════════════════════
 // MANAGED BLOCK UPDATE (CLAUDE.md / AGENTS.md)
 // ═══════════════════════════════════════════════════════════════════
 
-function applyManagedBlock(filePath, tplFn) {
+function ensureClaudeStopHookFile(dir, mark) {
+  const claudeDir = path.join(dir, '.claude');
+  const claudeSettings = path.join(claudeDir, 'settings.json');
+  fs.mkdirSync(claudeDir, { recursive: true });
+  if (!fs.existsSync(claudeSettings)) {
+    write(claudeSettings, tplClaudeSettings());
+    mark('add', '.claude/settings.json');
+    return;
+  }
+  const merged = ensureClaudeStopHook(claudeSettings);
+  mark(merged ? 'update' : 'skip', `.claude/settings.json (Stop hook ${merged ? 'merged' : 'already present'})`);
+}
+
+function ensurePendingGitignore(dir, mark) {
+  const gitignorePath = path.join(dir, '.gitignore');
+  const PENDING_ENTRY = '.memoc/.pending';
+  const gitignoreContent = fs.existsSync(gitignorePath)
+    ? fs.readFileSync(gitignorePath, 'utf8') : '';
+  const hasPendingEntry = gitignoreContent
+    .split(/\r?\n/)
+    .some(line => line.trim() === PENDING_ENTRY);
+  if (!hasPendingEntry) {
+    fs.appendFileSync(gitignorePath, (gitignoreContent.endsWith('\n') ? '' : '\n') + PENDING_ENTRY + '\n', 'utf8');
+    mark('update', '.gitignore (.memoc/.pending added)');
+  } else {
+    mark('skip', '.gitignore (.memoc/.pending already present)');
+  }
+}
+
+function printCommandHint() {
+  console.log('\n  Agent command fallback:');
+  console.log('    memoc summary');
+  console.log('    .\\.memoc\\bin\\memoc.cmd summary   # Windows');
+  console.log('    .memoc/bin/memoc summary          # macOS/Linux sh');
+  console.log('  If PATH fails once, use the project-local wrapper for the rest of the session.');
+}
+
+function applyManagedBlock(filePath, tplFn) {
   if (!fs.existsSync(filePath)) {
     write(filePath, tplFn());
     return 'add';
   }
   const src = fs.readFileSync(filePath, 'utf8');
-  const s = src.indexOf(MGMT_S);
-  const e = src.indexOf(MGMT_E);
-  if (s === -1 || e === -1) {
+  const range = findMarkedRange(src, MGMT_S, MGMT_E);
+  if (!range) {
     // No managed block — inject at end, preserving all user content
     write(filePath, src.trimEnd() + '\n\n' + managedBlock() + '\n');
     return 'inject';
   }
-  write(filePath, src.slice(0, s) + managedBlock() + src.slice(e + MGMT_E.length));
+  write(filePath, src.slice(0, range.s) + managedBlock() + src.slice(range.e + range.endMark.length));
   return 'update';
 }
 
@@ -1244,7 +1353,7 @@ function applyManagedBlock(filePath, tplFn) {
 // MAIN RUNNER
 // ═══════════════════════════════════════════════════════════════════
 
-function run(dir, forceUpdate) {
+function run(dir, forceUpdate, action = 'update') {
   const p       = scanProject(dir);
   const memDir  = path.join(dir, '.memoc');
   const isNew   = !fs.existsSync(path.join(memDir, 'boot.md'));
@@ -1288,7 +1397,7 @@ function run(dir, forceUpdate) {
       [path.join(memDir, '05-done-checklist.md'),      tplDoneChecklist],
       [path.join(memDir, '06-project-rules.md'),       tplProjectRules],
       [path.join(memDir, 'log.md'),                    tplLog],
-      [path.join(memDir, 'memoc-usage.md'),    tplContextForgeUsage],
+      [path.join(memDir, 'memoc-usage.md'),    tplMemocUsage],
       [path.join(memDir, 'systems/README.md'),         tplSystemsReadme],
       [path.join(memDir, 'wiki/index.md'),             tplWikiIndex],
       [path.join(memDir, 'wiki/sources.md'),           tplWikiSources],
@@ -1306,36 +1415,18 @@ function run(dir, forceUpdate) {
     }
 
     // Claude Code Stop hook — writes .memoc/.pending when git detects changes
-    const claudeDir      = path.join(dir, '.claude');
-    const claudeSettings = path.join(claudeDir, 'settings.json');
-    fs.mkdirSync(claudeDir, { recursive: true });
-    if (!fs.existsSync(claudeSettings)) {
-      write(claudeSettings, tplClaudeSettings());
-      mark('add', '.claude/settings.json');
-    } else {
-      const merged = ensureClaudeStopHook(claudeSettings);
-      mark(merged ? 'update' : 'skip', `.claude/settings.json (Stop hook ${merged ? 'merged' : 'already present'})`);
-    }
+    ensureClaudeStopHookFile(dir, mark);
 
     // .gitignore — add .memoc/.pending if not already present
-    const gitignorePath = path.join(dir, '.gitignore');
-    const PENDING_ENTRY = '.memoc/.pending';
-    const gitignoreContent = fs.existsSync(gitignorePath)
-      ? fs.readFileSync(gitignorePath, 'utf8') : '';
-    if (!gitignoreContent.includes(PENDING_ENTRY)) {
-      fs.appendFileSync(gitignorePath, (gitignoreContent.endsWith('\n') ? '' : '\n') + PENDING_ENTRY + '\n', 'utf8');
-      mark('update', '.gitignore (.memoc/.pending added)');
-    } else {
-      mark('skip', '.gitignore (.memoc/.pending already present)');
-    }
-
-    // PATH helpers — let agents run memoc even when the npm bin is not on PATH
+    ensurePendingGitignore(dir, mark);
+
+    // PATH helpers — let agents run memoc even when the npm bin is not on PATH
     ensurePathHelpers(dir, mark);
-    ensurePathRegistration(dir, mark);
-
-  } else {
+    ensurePathRegistration(dir, mark);
+
+  } else {
     // ── UPDATE MODE
-    console.log(`\n  memoc update — ${path.basename(dir)}`);
+    console.log(`\n  memoc ${action} — ${path.basename(dir)}`);
     console.log(`  Re-scanning project: ${p.isEmpty ? 'nothing detected' : stackStr(p.stack)}`);
     console.log();
 
@@ -1404,7 +1495,7 @@ function run(dir, forceUpdate) {
       [path.join(memDir, '05-done-checklist.md'),      tplDoneChecklist],
       [path.join(memDir, '06-project-rules.md'),       tplProjectRules],
       [path.join(memDir, 'log.md'),                    tplLog],
-      [path.join(memDir, 'memoc-usage.md'),    tplContextForgeUsage],
+      [path.join(memDir, 'memoc-usage.md'),    tplMemocUsage],
       [path.join(memDir, 'systems/README.md'),         tplSystemsReadme],
       [path.join(memDir, 'wiki/index.md'),             tplWikiIndex],
       [path.join(memDir, 'wiki/sources.md'),           tplWikiSources],
@@ -1416,13 +1507,15 @@ function run(dir, forceUpdate) {
       [path.join(memDir, 'wiki/global/README.md'),     tplWikiGlobalReadme],
       [path.join(dir,    'skills/project-memory-maintainer/SKILL.md'), tplSkillMaintainer],
     ];
-    for (const [fp, tpl] of addIfMissing) {
-      const rel = path.relative(dir, fp);
-      if (ensure(fp, tpl())) mark('add', rel);
-      // silently skip existing — user/agent owns them
-    }
-
-    // PATH helpers — let agents run memoc even when the npm bin is not on PATH
+    for (const [fp, tpl] of addIfMissing) {
+      const rel = path.relative(dir, fp);
+      if (ensure(fp, tpl())) mark('add', rel);
+      // silently skip existing — user/agent owns them
+    }
+
+    // PATH helpers — let agents run memoc even when the npm bin is not on PATH
+    ensureClaudeStopHookFile(dir, mark);
+    ensurePendingGitignore(dir, mark);
     ensurePathHelpers(dir, mark);
     ensurePathRegistration(dir, mark);
 
@@ -1430,17 +1523,18 @@ function run(dir, forceUpdate) {
     const logPath = path.join(memDir, 'log.md');
     if (fs.existsSync(logPath)) {
       fs.appendFileSync(logPath,
-        `\n## [${nowISO()}] update | Re-scanned: ${p.isEmpty ? 'nothing detected' : stackStr(p.stack)}\n`,
+        `\n## [${nowISO()}] ${action} | Re-scanned: ${p.isEmpty ? 'nothing detected' : stackStr(p.stack)}\n`,
         'utf8'
       );
       mark('append', '.memoc/log.md');
     }
   }
 
-  hideOnWindows(memDir);
-  console.log(log.join('\n'));
-  console.log('\n  Done.');
-}
+  hideOnWindows(memDir);
+  console.log(log.join('\n'));
+  printCommandHint();
+  console.log('\n  Done.');
+}
 
 // ═══════════════════════════════════════════════════════════════════
 // ADD — add entry file for a specific agent
@@ -1476,9 +1570,9 @@ function runAdd(dir) {
 // SEARCH
 // ═══════════════════════════════════════════════════════════════════
 
-function runSearch(dir, scope = 'memory') {
-  const rawArgs = process.argv.slice(3);
-  const opts = { mode: 'files', limit: 12, all: false };
+function runSearch(dir, scope = 'memory') {
+  const rawArgs = process.argv.slice(3);
+  const opts = { mode: 'files', limit: 12, all: false };
   const queryParts = [];
 
   for (let i = 0; i < rawArgs.length; i++) {
@@ -1499,12 +1593,12 @@ function runSearch(dir, scope = 'memory') {
     queryParts.push(arg);
   }
 
-  const query = queryParts.join(' ').toLowerCase();
-
-  const searchRoots = scope === 'project' ? [dir] : memorySearchRoots(dir);
+  const query = queryParts.join(' ').toLowerCase();
+
+  const searchRoots = scope === 'project' ? [dir] : memorySearchRoots(dir);
 
   if (!query) {
-    // No query — list searchable files sorted by recency
+    // No query — list searchable files sorted by recency
     const allFiles = [];
     function collectFile(fp) {
       if (!fs.existsSync(fp)) return;
@@ -1518,10 +1612,10 @@ function runSearch(dir, scope = 'memory') {
       for (const entry of fs.readdirSync(d)) {
         const fp = path.join(d, entry);
         try {
-          const st = fs.statSync(fp);
-          if (st.isDirectory()) {
-            if (!shouldSkipSearchDir(entry)) collectDir(fp);
-          } else if (isSearchableFile(fp, entry, st, scope)) collectFile(fp);
+          const st = fs.statSync(fp);
+          if (st.isDirectory()) {
+            if (!shouldSkipSearchDir(entry, scope)) collectDir(fp);
+          } else if (isSearchableFile(fp, entry, st, scope)) collectFile(fp);
         } catch {}
       }
     }
@@ -1542,15 +1636,15 @@ function runSearch(dir, scope = 'memory') {
 
   const matchesByFile = new Map(); // rel -> { matches: [], mtime: number }
 
-  function searchFile(fp) {
-    if (!fs.existsSync(fp)) return;
-    const rel = path.relative(dir, fp);
-    let mtime = 0;
-    try {
-      const st = fs.statSync(fp);
-      if (!isSearchableFile(fp, path.basename(fp), st, scope)) return;
-      mtime = st.mtimeMs;
-    } catch {}
+  function searchFile(fp) {
+    if (!fs.existsSync(fp)) return;
+    const rel = path.relative(dir, fp);
+    let mtime = 0;
+    try {
+      const st = fs.statSync(fp);
+      if (!isSearchableFile(fp, path.basename(fp), st, scope)) return;
+      mtime = st.mtimeMs;
+    } catch {}
     const lines = fs.readFileSync(fp, 'utf8').split('\n');
     lines.forEach((line, i) => {
       if (line.toLowerCase().includes(query)) {
@@ -1565,10 +1659,10 @@ function runSearch(dir, scope = 'memory') {
     for (const entry of fs.readdirSync(d)) {
       const fp = path.join(d, entry);
       try {
-        const st = fs.statSync(fp);
+        const st = fs.statSync(fp);
         if (st.isDirectory()) {
-          if (!shouldSkipSearchDir(entry)) walkDir(fp);
-        } else if (isSearchableFile(fp, entry, st, scope)) searchFile(fp);
+          if (!shouldSkipSearchDir(entry, scope)) walkDir(fp);
+        } else if (isSearchableFile(fp, entry, st, scope)) searchFile(fp);
       } catch {}
     }
   }
@@ -1583,63 +1677,116 @@ function runSearch(dir, scope = 'memory') {
   if (!matchesByFile.size) {
     console.log('No matches found.');
   } else if (opts.mode === 'files') {
-    const rows = [...matchesByFile.entries()]
-      .map(([file, { matches, mtime }]) => ({ file, count: matches.length, mtime }))
-      .sort((a, b) => b.count - a.count || b.mtime - a.mtime || a.file.localeCompare(b.file));
+    const rows = [...matchesByFile.entries()]
+      .map(([file, { matches, mtime }]) => ({ file, count: matches.length, mtime }))
+      .sort((a, b) =>
+        searchPriority(a.file, scope) - searchPriority(b.file, scope) ||
+        b.count - a.count ||
+        b.mtime - a.mtime ||
+        a.file.localeCompare(b.file)
+      );
     const limited = opts.all ? rows : rows.slice(0, opts.limit);
     console.log(limited.map(r => `${r.file}  ${r.count} match${r.count === 1 ? '' : 'es'}`).join('\n'));
     if (!opts.all && rows.length > limited.length) {
       console.log(`... ${rows.length - limited.length} more files. Use --all to show all, or --snippets for line matches.`);
     }
   } else {
-    const snippets = [];
-    for (const [file, { matches }] of matchesByFile.entries()) {
-      for (const m of matches) snippets.push(`${file}:${m.line}  ${m.text}`);
-    }
-    const limited = opts.all ? snippets : snippets.slice(0, opts.limit);
-    console.log(limited.join('\n'));
+    const snippets = [];
+    for (const [file, { matches }] of matchesByFile.entries()) {
+      for (const m of matches) snippets.push({ file, line: m.line, text: m.text });
+    }
+    snippets.sort((a, b) =>
+      searchPriority(a.file, scope) - searchPriority(b.file, scope) ||
+      a.file.localeCompare(b.file) ||
+      a.line - b.line
+    );
+    const limited = opts.all ? snippets : snippets.slice(0, opts.limit);
+    console.log(limited.map(m => `${m.file}:${m.line}  ${m.text}`).join('\n'));
     if (!opts.all && snippets.length > limited.length) {
       console.log(`... ${snippets.length - limited.length} more matches. Use --all to show all, or --limit N.`);
     }
   }
-}
-
-function memorySearchRoots(dir) {
-  return [
-    path.join(dir, '.memoc'),
-    path.join(dir, 'skills'),
-    path.join(dir, 'llms.txt'),
-    path.join(dir, 'AGENTS.md'),
-    path.join(dir, 'CLAUDE.md'),
-    ...Object.values(AGENT_REGISTRY).map(agent => path.join(dir, agent.file)),
-  ];
-}
-
-function shouldSkipSearchDir(name) {
-  return new Set([
+}
+
+function memorySearchRoots(dir) {
+  return [
+    path.join(dir, '.memoc'),
+    path.join(dir, 'skills'),
+    path.join(dir, 'llms.txt'),
+    path.join(dir, 'AGENTS.md'),
+    path.join(dir, 'CLAUDE.md'),
+    ...Object.values(AGENT_REGISTRY).map(agent => path.join(dir, agent.file)),
+  ];
+}
+
+function shouldSkipSearchDir(name, scope = 'memory') {
+  const skipped = new Set([
     '.git', 'node_modules', '.next', 'dist', 'build', 'out', 'coverage',
     'Saved', 'Intermediate', 'DerivedDataCache', 'Binaries',
     '.venv', 'venv', '__pycache__', '.pytest_cache',
-  ]).has(name);
+  ]);
+  if (scope === 'project') {
+    skipped.add('.memoc');
+    skipped.add('skills');
+    skipped.add('.claude');
+  }
+  return skipped.has(name);
 }
 
 function isSearchableFile(fp, name, st, scope = 'memory') {
   if (!st || !st.isFile()) return false;
   if (st.size > 1024 * 1024) return false;
+  if (scope === 'project' && isAgentMemoryFile(name)) return false;
   if (name === 'llms.txt' || name.endsWith('rules')) return true;
   const ext = path.extname(fp).toLowerCase();
-  if (scope === 'memory') {
-    return new Set(['.md', '.txt']).has(ext);
-  }
-  return new Set([
-    '.md', '.txt', '.json', '.jsonc', '.yaml', '.yml', '.toml', '.ini', '.env',
-    '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
-    '.py', '.rs', '.go', '.java', '.cs', '.cpp', '.cc', '.cxx', '.c', '.h', '.hpp', '.hxx',
-    '.html', '.css', '.scss', '.sass', '.vue', '.svelte',
-    '.sql', '.graphql', '.gql', '.sh', '.bash', '.zsh', '.ps1', '.bat', '.cmd',
-    '.xml', '.gradle', '.kts', '.cmake',
+  if (scope === 'memory') {
+    return new Set(['.md', '.txt']).has(ext);
+  }
+  return new Set([
+    '.md', '.txt', '.json', '.jsonc', '.yaml', '.yml', '.toml', '.ini', '.env',
+    '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+    '.py', '.rs', '.go', '.java', '.cs', '.cpp', '.cc', '.cxx', '.c', '.h', '.hpp', '.hxx',
+    '.html', '.css', '.scss', '.sass', '.vue', '.svelte',
+    '.sql', '.graphql', '.gql', '.sh', '.bash', '.zsh', '.ps1', '.bat', '.cmd',
+    '.xml', '.gradle', '.kts', '.cmake',
   ]).has(ext);
 }
+
+function isAgentMemoryFile(name) {
+  return new Set([
+    'AGENTS.md',
+    'CLAUDE.md',
+    'GEMINI.md',
+    'llms.txt',
+    '.cursorrules',
+    '.windsurfrules',
+    'copilot-instructions.md',
+  ]).has(name);
+}
+
+function searchPriority(file, scope = 'memory') {
+  if (scope !== 'memory') return 0;
+  const normalized = file.replace(/\\/g, '/');
+  const order = [
+    '.memoc/session-summary.md',
+    '.memoc/02-current-project-state.md',
+    '.memoc/04-handoff.md',
+    '.memoc/06-project-rules.md',
+    '.memoc/03-decisions.md',
+    '.memoc/log.md',
+    'AGENTS.md',
+    'CLAUDE.md',
+    'llms.txt',
+    '.memoc/00-project-brief.md',
+    '.memoc/00-agent-index.md',
+  ];
+  const exact = order.indexOf(normalized);
+  if (exact !== -1) return exact;
+  if (normalized.startsWith('.memoc/systems/')) return 20;
+  if (normalized.startsWith('.memoc/wiki/')) return 30;
+  if (normalized.startsWith('skills/')) return 40;
+  return 50;
+}
 
 // ═══════════════════════════════════════════════════════════════════
 // TOKENS — estimate token cost of current memory state
@@ -1810,15 +1957,16 @@ if (cmd === '--version' || cmd === '-v') {
 
 if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
   console.log('Usage: memoc <command>\n');
-  console.log('Commands:');
-  console.log('  init               Scaffold agent memory (auto-detects project, updates if already exists)');
-  console.log('  update             Force-update managed sections based on current project state');
-  console.log('  summary            Print a tiny status/resume overview');
+  console.log('Commands:');
+  console.log('  init               Scaffold agent memory (auto-detects project, updates if already exists)');
+  console.log('  update             Force-update managed sections based on current project state');
+  console.log('  upgrade            Refresh memoc runtime/wrappers and managed sections; preserve memory');
+  console.log('  summary            Print a tiny status/resume overview');
   console.log('  tokens             Estimate token cost of current memory files');
   console.log('  compress           Archive old log.md entries to keep file small');
   console.log('  add <agent>        Add entry file for a specific agent (run without args to list)');
-  console.log('  search "<query>"   Search memory/agent docs (use --snippets for line matches)');
-  console.log('  grep "<query>"     Search project source/text files (use --snippets for line matches)');
+  console.log('  search "<query>"   Search memory/agent docs (use --snippets for line matches)');
+  console.log('  grep "<query>"     Search project source/text files (use --snippets for line matches)');
   console.log('\nSearch flags:');
   console.log('  --files            Show file names and match counts, sorted by relevance + recency (default)');
   console.log('  --snippets         Show matching lines');
@@ -1829,14 +1977,15 @@ if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
   process.exit(0);
 }
 
-if (cmd === 'init')     { run(cwd, false);    process.exit(0); }
-if (cmd === 'update')   { run(cwd, true);     process.exit(0); }
+if (cmd === 'init')     { run(cwd, false);             process.exit(0); }
+if (cmd === 'update')   { run(cwd, true, 'update');    process.exit(0); }
+if (cmd === 'upgrade')  { run(cwd, true, 'upgrade');   process.exit(0); }
 if (cmd === 'summary')  { runSummary(cwd);    process.exit(0); }
 if (cmd === 'tokens')   { runTokens(cwd);     process.exit(0); }
 if (cmd === 'compress') { runCompress(cwd);   process.exit(0); }
 if (cmd === 'add')      { runAdd(cwd);        process.exit(0); }
-if (cmd === 'search')   { runSearch(cwd, 'memory');  process.exit(0); }
-if (cmd === 'grep')     { runSearch(cwd, 'project'); process.exit(0); }
+if (cmd === 'search')   { runSearch(cwd, 'memory');  process.exit(0); }
+if (cmd === 'grep')     { runSearch(cwd, 'project'); process.exit(0); }
 
 console.error(`Unknown command: ${cmd}`);
 console.error('Run "memoc --help" for usage.');