total-recall-brain 3.18.3 → 3.19.0

package/frontend/dist/index.html

@@ -17,7 +17,7 @@
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
     <title>Total Recall — Portable Memory</title>
-    <script type="module" crossorigin src="/assets/index-CGqvdwHT.js"></script>
+    <script type="module" crossorigin src="/assets/index-B6AfuKv9.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-B4RASWbV.css">
   </head>
   <body>

package/frontend/src/api/update.ts

@@ -25,8 +25,33 @@ export async function checkUpdate(): Promise<UpdateCheckResult> {
   }
 }
 
-export async function runUpdate(): Promise<{ success: boolean; message: string }> {
-  const res = await apiFetch(`${API_BASE}/api/update/run`, { method: 'POST' })
-  if (!res.ok) throw new Error(`Run update API error: ${res.status}`)
-  return res.json()
+export async function runUpdate(): Promise<{
+  success: boolean
+  message: string
+  summary?: {
+    latest?: string
+    updated?: number
+    failed?: number
+    up_to_date?: number
+    results?: { name: string; status: string; error?: string | null }[]
+  }
+}> {
+  const res = await apiFetch(`${API_BASE}/api/update/run`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ force: true }),
+  })
+  const data = await res.json().catch(() => ({}))
+  if (!res.ok) {
+    throw new Error(data.error || data.message || `Run update API error: ${res.status}`)
+  }
+  // API historically omitted success — treat finished-with-0-failures as success
+  const failed = Number(data.summary?.failed ?? 0)
+  const success =
+    typeof data.success === 'boolean' ? data.success : failed === 0 && data.summary?.skipped !== true
+  return {
+    success,
+    message: data.message || (success ? 'Package auto-update finished' : 'Package auto-update failed'),
+    summary: data.summary,
+  }
 }

package/frontend/src/pages/HealthPage.tsx

@@ -85,23 +85,19 @@ export default function HealthPage() {
     setUpdateError('')
     
     try {
-      await runUpdate()
-      
-      // Keep polling health to check when it goes down and recovers
-      let serverDown = false
-      const pollInterval = setInterval(async () => {
-        try {
-          const res = await fetchHealth()
-          if (serverDown && res.status === 'healthy') {
-            clearInterval(pollInterval)
-            window.location.reload()
-          }
-        } catch {
-          // Connection failed = server is offline / restarting
-          serverDown = true
-        }
-      }, 2000)
+      const result = await runUpdate()
+      if (!result.success) {
+        setUpdateError(result.message || 'Package auto-update reported failures')
+        setIsUpdating(false)
+        return
+      }
 
+      // Multi-repo npm update does not reboot this host — show success, optional reload
+      setIsUpdating(false)
+      setCheckMessage(
+        result.message ||
+          'Registered projects updated. Restart local daemon/server if you need new code in this process.',
+      )
     } catch (e) {
       setUpdateError((e as Error).message)
       setIsUpdating(false)

package/frontend/src/pages/SettingsPage.tsx

@@ -117,7 +117,28 @@ export default function SettingsPage({ activeBrainId }: { activeBrainId?: string
     setUpdateMessage(null);
     try {
       const res = await runUpdate();
-      setUpdateMessage(res.success ? 'Update complete. Restarting...' : 'Update failed: ' + res.message);
+      if (res.success) {
+        const s = res.summary;
+        const bits = [
+          s?.updated != null ? `${s.updated} updated` : null,
+          s?.up_to_date != null ? `${s.up_to_date} current` : null,
+          s?.latest ? `latest ${s.latest}` : null,
+        ].filter(Boolean);
+        setUpdateMessage(
+          bits.length
+            ? `Update complete — ${bits.join(' · ')}. Restart daemon/server if this host still runs old code.`
+            : res.message || 'Update complete.',
+        );
+      } else {
+        const failDetail = (res.summary?.results || [])
+          .filter((r) => r.status === 'failed')
+          .map((r) => `${r.name}: ${r.error || 'failed'}`)
+          .slice(0, 3)
+          .join('; ');
+        setUpdateMessage(
+          `Update failed: ${res.message}${failDetail ? ` (${failDetail})` : ''}`,
+        );
+      }
       const refreshed = await checkUpdate().catch(() => null);
       if (refreshed) {
         setUpdateInfo({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.18.3",
+  "version": "3.19.0",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [

package/src/cli/agent-dir.mjs

@@ -91,7 +91,21 @@ export function resolveAgentDir(layer = 'auto', targetPath = process.cwd()) {
  * @param {'global' | 'project' | 'auto'} [layer='auto']
  */
 export function resolveBrainDir(layer = 'auto', targetPath = process.cwd()) {
-  return getGlobalBrainDir();
+  // Match resolveAgentDir: AGENT_DIR override pins the agent root → brain under it.
+  if (process.env.AGENT_DIR) {
+    return path.join(process.env.AGENT_DIR, 'skills', 'total-recall');
+  }
+  if (layer === 'global') return getGlobalBrainDir();
+  if (layer === 'project') {
+    const project = detectProjectBrain(targetPath);
+    if (!project) {
+      throw new Error('No project brain found. Run `npx total-recall init --project` to create one.');
+    }
+    return project.brainDir;
+  }
+  // Auto: project-local wins if a project brain exists
+  const project = detectProjectBrain(targetPath);
+  return project ? project.brainDir : getGlobalBrainDir();
 }
 
 /**

package/src/cli/chat.mjs

@@ -10,7 +10,7 @@ import { callLocalRuntime, loadRuntimeConfig, checkRuntimeHealth } from '../core
 export default async function runChat(args) {
   console.log('🤖 Total Recall CLI Chat initialized. Type "exit" to quit.\n');
 
-  const configDir = path.join(resolveBrainDir(), 'config');
+  const configDir = path.join(resolveBrainDir('global'), 'config');
   
   let config;
   let caller;

package/src/cli/daemon.mjs

@@ -22,7 +22,8 @@ import { startDaemon, stopDaemon, readPid } from '../core/daemon-control.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, '..', '..');
-const BRAIN_DIR = resolveBrainDir();
+// System daemon always targets the global brain — never the cwd project vault.
+const BRAIN_DIR = resolveBrainDir('global');
 const LOG_FILE = path.join(BRAIN_DIR, 'logs', 'daemon.log');
 
 function commandExists(cmd) {

package/src/cli/dream.mjs

@@ -13,11 +13,9 @@
 
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveAgentDir, resolveBrainDir } from './agent-dir.mjs';
+import { resolveAgentDir, resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const AGENT_DIR = resolveAgentDir();
-const BRAIN_DIR = resolveBrainDir();
 
 function parseArgs(args) {
   const opts = { vault: null, help: false };
@@ -42,20 +40,26 @@ function printHelp() {
   Usage: total-recall dream [options]
 
   Options:
-    --vault <path>     Override vault directory (default: ~/.agent/memory-vault)
+    --vault <path>     Override vault directory
+    --global           Dream the global brain (default)
+    --project          Dream the project brain for the current repo
     --help, -h         Show this help
 `);
 }
 
 export default async function dream(args) {
-  const opts = parseArgs(args);
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  const effectiveLayer = layer === 'auto' ? 'global' : layer;
+  const opts = parseArgs(remainingArgs);
   if (opts.help) { printHelp(); return; }
 
-  const vaultDir = opts.vault || path.join(BRAIN_DIR, 'memory-vault');
-  const skillsDir = path.join(AGENT_DIR, 'skills');
-  const derivedDir = path.join(BRAIN_DIR, 'memory-derived');
-  const conflictsDir = path.join(BRAIN_DIR, 'memory-inbox', 'conflicts');
-  const instructionsFile = path.join(AGENT_DIR, 'INSTRUCTIONS.md');
+  const agentDir = resolveAgentDir(effectiveLayer);
+  const brainDir = resolveBrainDir(effectiveLayer);
+  const vaultDir = opts.vault || path.join(brainDir, 'memory-vault');
+  const skillsDir = path.join(agentDir, 'skills');
+  const derivedDir = path.join(brainDir, 'memory-derived');
+  const conflictsDir = path.join(brainDir, 'memory-inbox', 'conflicts');
+  const instructionsFile = path.join(agentDir, 'INSTRUCTIONS.md');
 
   console.error('\n  🌙 Starting dream cycle...\n');
   const startTime = Date.now();

package/src/cli/forget.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains } from './agent-dir.mjs';
 import { compileSurface } from '../core/surface.mjs';
 import { deleteNode } from '../core/vault.mjs';
+import { invalidate } from '../core/vault-cache.mjs';
 
 function printHelp() {
   console.log(`
@@ -65,12 +66,16 @@ export default async function forget(args) {
     }
     
     console.log(`  ✅ Soft-deleted ${count} nodes for project "${projectName}" (moved to .trash/)`);
+
+    // Files moved under .trash still invalidate the vault cache (watcher may lag)
+    invalidate(globalVaultDir);
     
     if (!remainingArgs.includes('--no-compile')) {
       console.log('  ⏳ Recompiling active memory surfaces and indexes in the background...');
       try {
         const { spawn } = await import('node:child_process');
-        const child = spawn(process.argv[0], [process.argv[1], 'compile'], {
+        // Soft-delete from global vault tags — recompile global surfaces
+        const child = spawn(process.argv[0], [process.argv[1], 'compile', '--global'], {
           detached: true,
           stdio: 'ignore'
         });
@@ -130,6 +135,9 @@ export default async function forget(args) {
     process.exit(1);
   }
 
+  // Drop cached nodes immediately (fs.watch may lag or miss same-process deletes)
+  invalidate(vaultDir);
+
   console.log(`  ✅ Deleted memory node "${slug}" from ${layerLabel} vault.`);
 
   // Recompile unless --no-compile
@@ -137,7 +145,11 @@ export default async function forget(args) {
     console.log('  ⏳ Recompiling active memory surfaces and indexes in the background...');
     try {
       const { spawn } = await import('node:child_process');
-      const child = spawn(process.argv[0], [process.argv[1], 'compile'], {
+      // Pass layer so project forget recompiles the project brain, not auto/wrong vault
+      const compileArgs = [process.argv[1], 'compile'];
+      if (layer === 'project') compileArgs.push('--project');
+      else if (layer === 'global') compileArgs.push('--global');
+      const child = spawn(process.argv[0], compileArgs, {
         detached: true,
         stdio: 'ignore'
       });

package/src/cli/friction.mjs

@@ -9,7 +9,7 @@ export default async function runFriction(args) {
   console.log(`[Friction] 🔍 Analyzing logs for workflow bottlenecks...`);
   
   // Default path for watchdog logs
-  const logPath = args[0] || path.join(resolveBrainDir(), 'logs', 'watchdog.jsonl');
+  const logPath = args[0] || path.join(resolveBrainDir('global'), 'logs', 'watchdog.jsonl');
   
   const result = await detectFriction(logPath);
   if (!result) {

package/src/cli/import-rules.mjs

@@ -8,10 +8,11 @@
 
 import path from 'node:path';
 import { detectAndImport } from '../core/import-rules.mjs';
-import { resolveAgentDir, resolveBrainDir } from './agent-dir.mjs';
+import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
 
 export async function run(argv = []) {
-  const args = argv.slice(3); // strip node, script, 'import'
+  const rawArgs = argv.slice(3); // strip node, script, 'import'
+  const { layer, remainingArgs: args } = parseLayerFlag(rawArgs);
 
   const dirs = [];
   let force  = false;
@@ -33,7 +34,8 @@ export async function run(argv = []) {
   // Default: search cwd
   if (dirs.length === 0) dirs.push(process.cwd());
 
-  const brainDir = resolveBrainDir();
+  // auto → project vault when present (import rules for this repo)
+  const brainDir = resolveBrainDir(layer);
   const vaultDir = path.join(brainDir, 'memory-vault');
 
   console.log(`\n🔍 Scanning for rule files in: ${dirs.join(', ')}\n`);
@@ -90,12 +92,15 @@ all future AI sessions.
 
 Options:
   --dir <path>   Directory to search (default: current directory)
+  --global       Import into the global vault
+  --project      Import into the project vault (default: auto when present)
   --force        Re-import files that were previously imported
   --dry-run      Show what would be imported without writing anything
   --help         Show this help
 
 Examples:
   npx total-recall import
+  npx total-recall import --project
   npx total-recall import --dir ~/my-project
   npx total-recall import --force --dry-run
 `);

package/src/cli/ingest.mjs

@@ -16,8 +16,9 @@
 import path from 'node:path';
 import { resolveAgentDir, resolveBrainDir } from './agent-dir.mjs';
 
-const AGENT_DIR = resolveAgentDir();
-const BRAIN_DIR = resolveBrainDir();
+// Session ingest lands in the global brain by default.
+const AGENT_DIR = resolveAgentDir('global');
+const BRAIN_DIR = resolveBrainDir('global');
 
 function parseArgs(args) {
   const opts = { sources: null, watch: false, help: false };

package/src/cli/lint.mjs

@@ -17,11 +17,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveAgentDir, resolveBrainDir } from './agent-dir.mjs';
+import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const AGENT_DIR = resolveAgentDir();
-const BRAIN_DIR = resolveBrainDir();
 
 function parseArgs(args) {
   const opts = { vault: null, strict: false, json: false, help: false, okf: false };
@@ -47,7 +45,9 @@ function printHelp() {
   Usage: total-recall lint [options]
 
   Options:
-    --vault <path>     Override vault directory (default: ~/.agent/memory-vault)
+    --vault <path>     Override vault directory (default: global brain vault)
+    --global           Lint the global vault (default)
+    --project          Lint the project vault for the current repo
     --strict           Treat warnings as errors (exit 1 on any issue)
     --okf              Verify OKF v0.1 draft metadata compliance
     --json             Output results as JSONL
@@ -60,10 +60,13 @@ function printHelp() {
 }
 
 export default async function lint(args) {
-  const opts = parseArgs(args);
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  // Default layer is global when no --project/--global (matches help text)
+  const effectiveLayer = layer === 'auto' ? 'global' : layer;
+  const opts = parseArgs(remainingArgs);
   if (opts.help) { printHelp(); return; }
 
-  const vaultDir = opts.vault || path.join(BRAIN_DIR, 'memory-vault');
+  const vaultDir = opts.vault || path.join(resolveBrainDir(effectiveLayer), 'memory-vault');
 
   if (opts.okf) {
     const { lintOkfCompliance } = await import('../core/okf-adapter.mjs');

package/src/cli/rebuild.mjs

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { compileSurface } from '../core/surface.mjs';
 import { detectIndexDrift } from '../core/drift-detector.mjs';
-import { resolveAgentDir, resolveBrainDir } from './agent-dir.mjs';
+import { resolveAgentDir, resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
 import { logger } from '../core/logger.mjs';
 
 /**
@@ -14,8 +14,9 @@ import { logger } from '../core/logger.mjs';
  */
 
 export async function runRebuild(options = {}) {
-  const agentDir = resolveAgentDir();
-  const brainDir = resolveBrainDir();
+  const layer = options.layer || 'auto';
+  const agentDir = resolveAgentDir(layer);
+  const brainDir = resolveBrainDir(layer);
   const vaultDir = path.join(brainDir, 'memory-vault');
   const skillsDir = path.join(agentDir, 'skills');
   const derivedDir = path.join(brainDir, 'memory-derived');
@@ -82,7 +83,11 @@ export async function runRebuild(options = {}) {
 }
 
 export default async function cli(args) {
-  const options = { check: args.includes('--check') };
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  const options = {
+    check: remainingArgs.includes('--check'),
+    layer,
+  };
   const code = await runRebuild(options);
   process.exit(code);
 }

package/src/cli/remember.mjs

@@ -5,6 +5,7 @@ import matter from 'gray-matter';
 import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains, defaultLayerForCategory } from './agent-dir.mjs';
 import { compileSurface } from '../core/surface.mjs';
 import { writeNodeValidatedAsync } from '../core/validated-write.mjs';
+import { defaultTitleFromBody } from '../core/memory-title.mjs';
 
 function printHelp() {
   console.log(`
@@ -243,8 +244,12 @@ export default async function remember(args) {
   // Create individual SSSS v2 node in the vault
   const contentHash = crypto.createHash('md5').update(bodyContent).digest('hex').slice(0, 8);
   const finalSlug = slug || `${category}-${contentHash}`;
-  const truncatedContent = bodyContent.slice(0, 50) + (bodyContent.length > 50 ? '...' : '');
-  const finalTitle = title || `Self-captured memory: ${truncatedContent.replace(/\n/g, ' ')}`;
+  // Provenance lives in source.type + tags — not a title prefix
+  const finalTitle = title || defaultTitleFromBody(bodyContent);
+  const finalTags = Array.isArray(tags) ? [...tags] : [];
+  if (!finalTags.includes('self-captured') && !title) {
+    finalTags.push('self-captured');
+  }
 
   const now = new Date().toISOString();
   
@@ -264,12 +269,13 @@ export default async function remember(args) {
     source: {
       type: 'remember-cli',
       session_id: process.env.TR_SESSION_ID || 'remember-session',
-      evidence_count: 1
+      evidence_count: 1,
+      capture: 'self',
     },
     supersedes: [],
     superseded_by: null,
     contradicts: [],
-    tags,
+    tags: finalTags,
     related,
     routes_to_skills: [],
     sentiment_polarity: type.toLowerCase() === 'preference' ? 'preference' : 'descriptive',
@@ -309,8 +315,9 @@ export default async function remember(args) {
             const oldTitle = (data.title || '').trim().toLowerCase();
             const newTitle = finalTitle.trim().toLowerCase();
             
-            const words1 = new Set(bodyContent.toLowerCase().match(/\\b\\w+\\b/g) || []);
-            const words2 = new Set((oldContent || '').toLowerCase().match(/\\b\\w+\\b/g) || []);
+            // Word tokens for Jaccard similarity (must be real \b/\w, not double-escaped literals)
+            const words1 = new Set(bodyContent.toLowerCase().match(/\b\w+\b/g) || []);
+            const words2 = new Set((oldContent || '').toLowerCase().match(/\b\w+\b/g) || []);
             const intersection = new Set([...words1].filter(x => words2.has(x)));
             const union = new Set([...words1, ...words2]);
             const similarity = union.size === 0 ? 0 : intersection.size / union.size;
@@ -325,14 +332,10 @@ export default async function remember(args) {
               data.superseded_by = finalSlug;
               data.updated = now;
               node.supersedes = [...(node.supersedes || []), data.slug];
-              
-              const lines = ['---'];
-              for (const key of Object.keys(data)) {
-                lines.push(`${key}: ${JSON.stringify(data[key])}`);
-              }
-              lines.push('---');
-              lines.push(oldContent);
-              fs.writeFileSync(p, lines.join('\n'));
+
+              // Use gray-matter so nested objects/arrays stay valid YAML
+              const bodyOut = (oldContent || '').trim();
+              fs.writeFileSync(p, matter.stringify(bodyOut ? `${bodyOut}\n` : '', data), 'utf8');
             }
           }
         }
@@ -360,7 +363,10 @@ export default async function remember(args) {
   console.log('  ⏳ Recompiling active memory surfaces and indexes in the background...');
   try {
     const { spawn } = await import('node:child_process');
-    const child = spawn(process.argv[0], [process.argv[1], 'compile'], {
+    const compileArgs = [process.argv[1], 'compile'];
+    if (layer === 'project') compileArgs.push('--project');
+    else if (layer === 'global') compileArgs.push('--global');
+    const child = spawn(process.argv[0], compileArgs, {
       detached: true,
       stdio: 'ignore'
     });

package/src/cli/secret.mjs

@@ -985,9 +985,12 @@ export default async function secretCli(argv) {
 
     if (opts.command === 'check-surfaces') {
       const texts = [];
+      const agentRoot = path.dirname(path.dirname(brainDir)); // …/skills/total-recall → …/.agent (or similar)
       const candidates = [
-        path.join(brainDir, 'INSTRUCTIONS.md'),
         path.join(process.cwd(), 'INSTRUCTIONS.md'),
+        path.join(process.cwd(), 'AGENTS.md'),
+        path.join(agentRoot, 'INSTRUCTIONS.md'),
+        path.join(brainDir, 'INSTRUCTIONS.md'), // legacy
         path.join(brainDir, 'openwiki'),
       ];
       for (const c of candidates) {

package/src/cli/share.mjs

@@ -1,5 +1,5 @@
 import crypto from 'node:crypto';
-import { parseLayerFlag, resolveBrainDir, getBothBrains, defaultLayerForCategory } from './agent-dir.mjs';
+import { parseLayerFlag, resolveAgentDir, resolveBrainDir, getBothBrains, defaultLayerForCategory } from './agent-dir.mjs';
 import { createMemoryNode } from '../core/vault.mjs';
 import { writeNodeValidatedAsync } from '../core/validated-write.mjs';
 import { addToQueue } from '../core/research-queue.mjs';
@@ -128,10 +128,12 @@ export default async function share(args) {
   }
 
   const resolvedBrainDir = resolveBrainDir(layer);
+  const resolvedAgentDir = resolveAgentDir(layer);
   const vaultDir = path.join(resolvedBrainDir, 'memory-vault');
-  const skillsDir = path.join(resolvedBrainDir, '..', '..');
+  // skillsDir must be <agent>/.agent/skills (or ~/.agent/skills), not the agent root
+  const skillsDir = path.join(resolvedAgentDir, 'skills');
   const derivedDir = path.join(resolvedBrainDir, 'memory-derived');
-  const instructionsFile = path.join(skillsDir, '..', 'INSTRUCTIONS.md');
+  const instructionsFile = path.join(resolvedAgentDir, 'INSTRUCTIONS.md');
 
   const slugBase = category || 'facts';
   const slug = `${slugBase}-${crypto.randomBytes(4).toString('hex')}`;

package/src/cli/skill-projection.mjs

@@ -70,6 +70,22 @@ function pathExists(filePath) {
   }
 }
 
+// Marker written by tools like repo-expert-generate.mjs into any SKILL.md
+// they produce. A real (non-symlink) directory carrying this marker is
+// leftover tool output, not a user's hand-authored skill — it is always safe
+// to heal back onto the canonical source, even without --force.
+const AUTO_GENERATED_MARKER = '**Auto-generated** by `npx total-recall';
+
+function isStaleGeneratedDir(entryPath) {
+  try {
+    if (!fs.statSync(entryPath).isDirectory()) return false;
+    const content = fs.readFileSync(path.join(entryPath, 'SKILL.md'), 'utf8');
+    return content.includes(AUTO_GENERATED_MARKER);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Skill source roots, in priority order. The canonical Total Recall location
  * (.agent/skills, singular) wins, but we also scan the Antigravity-native
@@ -115,7 +131,10 @@ export function discoverRepoSkills(agentDir) {
  * Idempotent, self-healing, and strictly additive: a symlink that is broken or
  * stale is refreshed even without --force; a *real* (non-symlink) entry is
  * never clobbered unless --force (so a user's own skill always wins a name
- * collision); a skill whose source already *is* the destination is left alone.
+ * collision) — UNLESS that real entry is itself stale tool output (carries
+ * the auto-generated marker), in which case it is healed back onto the
+ * canonical source; a skill whose source already *is* the destination is
+ * left alone.
  */
 export function projectSkillsAsCommands(destDir, skills, opts = {}) {
   fs.mkdirSync(destDir, { recursive: true });
@@ -138,7 +157,7 @@ export function projectSkillsAsCommands(destDir, skills, opts = {}) {
           continue;
         }
         fs.unlinkSync(linkPath); // stale, broken, or --force → refresh
-      } else if (!opts.force) {
+      } else if (!opts.force && !isStaleGeneratedDir(linkPath)) {
         written.push({ name: skill.name, action: 'skipped' }); // user's real file/dir wins
         continue;
       } else {

package/src/cli/snapshot.mjs

@@ -1,5 +1,5 @@
 import { createSnapshot, listSnapshots, rollbackVault } from '../core/snapshot.mjs';
-import { resolveAgentDir, resolveBrainDir } from './agent-dir.mjs';
+import { resolveAgentDir, resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
 import { compileSurface } from '../core/surface.mjs';
 import path from 'path';
 
@@ -24,20 +24,22 @@ function printHelp() {
     rollback <id>      Restore the vault to a specific snapshot ID
 
   Options:
-    --help, -h         Show this help
+    --global / --project  Target brain layer (default: auto — project if present)
+    --help, -h            Show this help
 `);
 }
 
 export default async function snapshotCli(args) {
-  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  if (remainingArgs.length === 0 || remainingArgs.includes('--help') || remainingArgs.includes('-h')) {
     printHelp();
     return;
   }
 
-  const command = args[0];
+  const command = remainingArgs[0];
 
   if (command === 'create') {
-    const reason = args.slice(1).join(' ') || 'manual';
+    const reason = remainingArgs.slice(1).join(' ') || 'manual';
     console.log('📸 Creating snapshot...');
     const result = createSnapshot(reason);
     if (result.success) {
@@ -69,7 +71,7 @@ export default async function snapshotCli(args) {
   }
 
   else if (command === 'rollback') {
-    const id = args[1];
+    const id = remainingArgs[1];
     if (!id) {
       console.error('❌ You must provide a snapshot ID to rollback to.');
       console.error('Usage: total-recall snapshot rollback <id>');
@@ -84,8 +86,8 @@ export default async function snapshotCli(args) {
       console.log(`✅ Rollback successful.`);
       console.log(`🔄 Recompiling derived indexes from restored vault...`);
       
-      const agentDir = resolveAgentDir();
-      const brainDir = resolveBrainDir();
+      const agentDir = resolveAgentDir(layer);
+      const brainDir = resolveBrainDir(layer);
       await compileSurface({
         vaultDir: path.join(brainDir, 'memory-vault'),
         skillsDir: path.join(agentDir, 'skills'),

package/src/cli/update.mjs

@@ -16,7 +16,8 @@ import {
 } from '../core/package-auto-update.mjs';
 import { brainDir } from '../core/config.mjs';
 
-function parseArgs(args) {
+/** @param {string[]} args */
+export function parseArgs(args) {
   const opts = {
     apply: false,
     force: false,