total-recall-brain 3.43.3 → 3.45.0

package/src/cli/connect.mjs

@@ -80,11 +80,10 @@ export const CLIENTS = {
   },
   openclaw: {
     label: 'OpenClaw',
-    mode: 'openclaw',
+    mode: 'symlink',
     enforcement: 'enforced',
     enforcementReason: 'before_tool_call hook denies unreceipted tool calls with exit 2',
-    memoryTarget: 'MEMORY.md',
-    agentsTarget: 'AGENTS.md',
+    target: 'AGENTS.md',
   },
   cursor: {
     label: 'Cursor',
@@ -880,32 +879,6 @@ export default async function connect(args) {
       result.notes.push(`  DeepSeek Harness MEMORY.md → ${globalMemPath}`);
     }
     result.notes.push(`  DeepSeek Harness AGENTS.md → INSTRUCTIONS.md`);
-  } else if (preset.mode === 'openclaw') {
-    // OpenClaw: write MEMORY.md + symlink AGENTS.md in cwd
-    const instructions = readInstructions(cwd, agentDir);
-    if (!instructions) throw new Error('No INSTRUCTIONS.md found. Run npx total-recall init or compile first.');
-    // MEMORY.md — curated facts extracted from instructions
-    const memPath = path.join(cwd, preset.memoryTarget);
-    if (!fs.existsSync(memPath) || opts.force) {
-      fs.writeFileSync(memPath, instructions, 'utf8');
-    }
-    // AGENTS.md — symlink to INSTRUCTIONS.md
-    const agentsPath = path.join(cwd, preset.agentsTarget);
-    if (pathExists(agentsPath)) {
-      if (opts.force) {
-        try {
-          fs.unlinkSync(agentsPath);
-        } catch {
-          fs.rmSync(agentsPath, { force: true, recursive: true });
-        }
-        fs.symlinkSync('INSTRUCTIONS.md', agentsPath);
-      }
-    } else {
-      fs.symlinkSync('INSTRUCTIONS.md', agentsPath);
-    }
-    result.projection = { targetPath: memPath, action: 'written' };
-    result.notes.push(`  OpenClaw MEMORY.md written to ${memPath}`);
-    result.notes.push(`  OpenClaw AGENTS.md → INSTRUCTIONS.md`);
   } else if (preset.mode === 'vault') {
     result.projection = writeVaultProjection(agentDir, preset, opts);
     const folderName = result.projection.folderName || preset.folderName;

package/src/cli/context.mjs

@@ -61,6 +61,7 @@ async function printCompacted({ query, actions, budget, format, version, rulesHa
     if (format !== 'json') return result.context;
     const payload = { ready: true, compacted: true, ranking: result.ranking, context: result.context, counts: result.counts,
       stats: { version, rules_hash: rulesHash, budget, retrieval: summarizeRetrieval(knowledge?.summary), token_measurement: 'estimated_chars_divided_by_four' } };
+    if (result.evidenceStart !== undefined) payload.evidence_start = result.evidenceStart;
     for (let index = 0; index < 10; index++) {
       const tokens = estimateTokens(`${JSON.stringify(payload)}\n`);
       if (tokens === payload.stats.total_tokens) break;

package/src/cli/dream.mjs

@@ -1,84 +1,108 @@
-/**
- * total-recall dream
- *
- * Manually trigger a single dream cycle (Light → REM → Deep Sleep).
- *
- * Usage:
- *   npx total-recall dream [options]
- *
- * Options:
- *   --vault <path>     Override vault directory (default: ~/.agent/memory-vault)
- *   --help             Show this help
- */
-
+/** Run one dream cycle per selected brain. Scheduling belongs to automations. */
+import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { resolveAgentDir, resolveBrainDir, parseLayerFlag, resolveSurfaceDir } from './agent-dir.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import { resolveAgentDir, resolveBrainDir, resolveSurfaceDir, getGlobalBrainDir, getGlobalAgentDir } from './agent-dir.mjs';
+import { listUpdateRoots } from '../core/package-auto-update.mjs';
 
-function parseArgs(args) {
-  const opts = { vault: null, help: false };
+export function parseDreamArgs(args) {
+  const opts = { layer: 'global', allBrains: false, dryRun: false, json: false };
+  let explicitLayer;
   for (let i = 0; i < args.length; i++) {
-    switch (args[i]) {
-      case '--vault': opts.vault = args[++i]; break;
-      case '--help': case '-h': opts.help = true; break;
-    }
+    const arg = args[i];
+    if (arg === '--all-brains') opts.allBrains = true;
+    else if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--global' || arg === '--project') {
+      if (explicitLayer && explicitLayer !== arg) throw new Error('Choose --global or --project.');
+      explicitLayer = arg;
+      opts.layer = arg.slice(2);
+    } else if (arg === '--vault') {
+      if (!args[i + 1] || args[i + 1].startsWith('-')) throw new Error('--vault requires a path.');
+      opts.vault = path.resolve(args[++i]);
+    } else throw new Error(`Unknown dream option: ${arg}`);
   }
+  if (opts.allBrains && (opts.vault || explicitLayer)) throw new Error('--all-brains cannot be combined with --vault, --global or --project.');
   return opts;
 }
 
-function printHelp() {
-  console.log(`
-  total-recall dream — Manually trigger a dream cycle
+function target(brainDir, agentDir, surfaceDir, root) {
+  return { root, brainDir, vaultDir: path.join(brainDir, 'memory-vault'),
+    derivedDir: path.join(brainDir, 'memory-derived'), skillsDir: path.join(agentDir, 'skills'),
+    conflictsDir: path.join(brainDir, 'memory-inbox', 'conflicts'),
+    instructionsFile: path.join(surfaceDir, 'INSTRUCTIONS.md') };
+}
 
-  The dream cycle runs three phases:
-    1. Light Sleep — Scan vault for recent modifications
-    2. REM         — Score, conflict-check, and promote/decay candidates
-    3. Deep Sleep  — Recompile the surface (indexes + INSTRUCTIONS.md)
+export function discoverDreamBrains({ brainDir = getGlobalBrainDir(), agentDir = getGlobalAgentDir(), roots } = {}) {
+  const brains = [target(brainDir, agentDir, agentDir, agentDir)];
+  const seen = new Set([fs.existsSync(brainDir) ? fs.realpathSync(brainDir) : path.resolve(brainDir)]);
+  for (const { root } of listUpdateRoots({ brainDir, roots })) {
+    // Fleet selection is explicit. AGENT_DIR must not redirect project brains.
+    const projectAgent = ['.agent', '.agents'].map(name => path.join(root, name))
+      .find(dir => fs.existsSync(path.join(dir, 'skills/total-recall/memory-vault'))
+        || fs.existsSync(path.join(dir, 'skills/total-recall/SKILL.md')));
+    if (!projectAgent) continue;
+    const projectBrain = path.join(projectAgent, 'skills/total-recall');
+    const real = fs.realpathSync(projectBrain);
+    if (seen.has(real)) continue;
+    seen.add(real);
+    brains.push(target(projectBrain, projectAgent, root, root));
+  }
+  return brains;
+}
 
-  Usage: total-recall dream [options]
+async function previewDecay({ vaultDir, derivedDir }) {
+  const [{ loadNodes }, { readAccess }, { decayCandidates }] = await Promise.all([
+    import('../core/vault.mjs'), import('../core/access-ledger.mjs'), import('../core/optimizer.mjs'),
+  ]);
+  return decayCandidates(loadNodes(vaultDir), readAccess(derivedDir)).map(node => node.slug);
+}
 
-  Options:
-    --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
-`);
+function printHelp() {
+  console.log(`Usage: total-recall dream [--global | --project | --all-brains] [--vault <path>] [--dry-run] [--json]
+  Dream consolidates memory and runs phase 4 decay.
+  --all-brains  Run the global brain and registered project brains on this node, one at a time.
+  --dry-run     List brains and decay candidates without changes or runtime calls.
+  --json        Print an array of per-brain results.
+  --help, -h    Show this help.`);
 }
 
-export default async function dream(args) {
-  const { layer, remainingArgs } = parseLayerFlag(args);
-  const effectiveLayer = layer === 'auto' ? 'global' : layer;
-  const opts = parseArgs(remainingArgs);
+export default async function dream(args = [], dependencies = {}) {
+  let opts;
+  try { opts = parseDreamArgs(args); }
+  catch (error) { console.error(error.message); process.exitCode = 2; return; }
   if (opts.help) { printHelp(); return; }
-
-  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(resolveSurfaceDir(effectiveLayer), 'INSTRUCTIONS.md');
-
-  console.error('\n  🌙 Starting dream cycle...\n');
-  const startTime = Date.now();
-
+  const results = [];
   try {
-    const { runDreamCycle } = await import('../core/dream.mjs');
-    const result = await runDreamCycle({
-      vaultDir,
-      skillsDir,
-      derivedDir,
-      conflictsDir,
-      instructionsFile,
-    });
-
-    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-    console.error(`\n  ✅ Dream cycle complete (${elapsed}s) — status: ${result.status}`);
-  } catch (err) {
-    console.error(`\n  ❌ Dream cycle failed: ${err.message}`);
-    console.error(err.stack);
-    process.exit(1);
-  }
+    const brains = opts.allBrains ? (dependencies.discover || discoverDreamBrains)() : [
+      target(resolveBrainDir(opts.layer), resolveAgentDir(opts.layer), resolveSurfaceDir(opts.layer), resolveSurfaceDir(opts.layer)),
+    ];
+    if (opts.vault) {
+      brains[0].vaultDir = opts.vault;
+      brains[0].brainDir = path.dirname(opts.vault);
+      brains[0].derivedDir = path.join(brains[0].brainDir, 'memory-derived');
+      brains[0].conflictsDir = path.join(brains[0].brainDir, 'memory-inbox', 'conflicts');
+    }
+    const run = opts.dryRun ? null : (dependencies.run || (await import('../core/dream.mjs')).runDreamCycle);
+    for (const brain of brains) {
+      let row;
+      try {
+        if (!fs.existsSync(brain.vaultDir)) throw new Error(`Vault not found: ${brain.vaultDir}`);
+        const result = opts.dryRun
+          ? { status: 'dry_run', decay_candidates: await (dependencies.preview || previewDecay)(brain) }
+          : await run(brain);
+        row = { ...brain, ...result };
+      } catch (error) { row = { ...brain, status: 'failed', error: error.message }; }
+      results.push(row);
+      if (!opts.json) {
+        console.log(`${row.brainDir}: ${row.status}${row.error ? ` — ${row.error}` : ''}`);
+        if (row.decay_candidates) console.log(`  Decay candidates: ${row.decay_candidates.join(', ') || 'none'}`);
+        for (const error of row.errors || []) console.error(`  ${error}`);
+      }
+    }
+  } catch (error) { results.push({ status: 'failed', error: error.message }); }
+  if (opts.json) console.log(JSON.stringify(results, null, 2));
+  else if (results.length === 1 && results[0].error && !results[0].brainDir) console.error(results[0].error);
+  if (results.some(row => !['success', 'dry_run'].includes(row.status))) process.exitCode = 1;
+  return results;
 }

package/src/cli/harness.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/** Legacy command door. Native harness behavior is owned by the Meta Harness plugin. */
+/** Legacy command door. Native harness behavior is owned by the Metaharness plugin. */
 import { checkAnyReceipt, findRoot, ACK_COMMAND } from '../core/preflight-receipt.mjs';
 import path from 'node:path';
 
@@ -11,9 +11,9 @@ async function callPlugin(subcommand, args, options = {}) {
   const result = await runPluginCommand(plugin, { subcommand, args: [...args, '--json'], timeoutMs: 600000, ...options });
   let data;
   try { data = JSON.parse(result.output); }
-  catch { throw new Error(`Meta Harness returned invalid JSON for ${subcommand}`); }
+  catch { throw new Error(`Metaharness returned invalid JSON for ${subcommand}`); }
   if (!result.ok || data?.ok === false) {
-    const error = new Error(data?.error || `Meta Harness ${subcommand} failed`);
+    const error = new Error(data?.error || `Metaharness ${subcommand} failed`);
     error.result = data;
     throw error;
   }
@@ -32,7 +32,7 @@ export async function run(argv = []) {
   const asJson = args.includes('--json');
   try {
     if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
-      console.log('Usage: total-recall harness list|usage [--node ID] [--json] | dispatch <id> <task> [--node ID --cwd /remote/workspace] [--write] [--allow-unknown-auth] [--json] | council <task> [--allow-unknown-auth] [--json]. Harness operations delegate to the Meta Harness plugin.');
+      console.log('Usage: total-recall harness list|usage [--node ID] [--json] | dispatch <id> <task> [--node ID --cwd /remote/workspace] [--write] [--allow-unknown-auth] [--json] | council <task> [--allow-unknown-auth] [--json]. Harness operations delegate to the Metaharness plugin.');
       return;
     }
     const command = args[0] || 'list', positional = [];

package/src/cli/help.mjs

@@ -19,7 +19,7 @@ const ROOT = path.join(__dirname, '..', '..');
 export default async function run(argv) {
   const args = argv || [];
   const requestedTopic = args.find(arg => !arg.startsWith('-'))?.toLowerCase() || null;
-  const topic = ({ server: 'start', 'startup-check': 'startup' })[requestedTopic] || requestedTopic;
+  const topic = ({ 'startup-check': 'startup' })[requestedTopic] || requestedTopic;
   const isJson = args.includes('--json') || args.includes('-j');
 
   const cliRefPath = path.join(ROOT, 'docs', 'reference', 'cli-reference.md');

package/src/cli/ingest-okf.mjs

@@ -11,7 +11,7 @@ export async function runOkfIngest(args) {
     dryRun: false,
     category: null,
     importance: null,
-    onConflict: 'warn',
+    onConflict: 'skip',
     typeMap: null,
     help: false
   };
@@ -118,10 +118,10 @@ function printIngestOkfHelp() {
 
   Options:
     --dry-run                 Validate concepts and preview import without writing
-    --category <name>         Override and force category for all imported concepts
+    --category <name>         Choose a descriptive category for imported concepts
     --importance <1-5>        Override default importance (default: 3)
-    --on-conflict <strategy>  Strategy for duplicate slugs: 'skip' | 'warn' | 'overwrite' (default: warn)
-    --type-map <mapping>      Custom type mappings. Format: "Type A=facts,Type B=concepts"
+    --on-conflict <strategy>  'skip' (default), 'warn' (report and skip), or 'overwrite' (same imported concept)
+    --type-map <mapping>      Map types to descriptive categories, e.g. "Type A=facts,Type B=concepts"
     --global                  Target the global brain
     --project                 Target the project brain (default)
     --help, -h                Show this help

package/src/cli/init.mjs

@@ -407,31 +407,6 @@ export default async function init(args) {
     logOk('Default memory vault seeded');
   }
 
-  // ── Step 3.5: Seed the onboarding interview task ──
-  logStep('3.5/4', 'Seeding onboarding interview into scheduler queue');
-
-  const queueDir = path.join(brainDir, 'scheduler', 'queue');
-  const interviewDest = path.join(queueDir, 'onboarding-interview.md');
-  const interviewSrc = path.join(ROOT, 'templates', 'onboarding-interview.md');
-
-  if (!fs.existsSync(interviewDest)) {
-    if (!opts.dryRun) {
-      fs.mkdirSync(queueDir, { recursive: true });
-      if (fs.existsSync(interviewSrc)) {
-        const now = new Date().toISOString();
-        const content = fs.readFileSync(interviewSrc, 'utf8').replace(/\{\{CREATED_AT\}\}/g, now);
-        fs.writeFileSync(interviewDest, content);
-        logOk('Onboarding interview task queued — agent will conduct it on first chat');
-      } else {
-        logWarn('Interview template not found — skipping');
-      }
-    } else {
-      log(`  Would write ${path.relative(cwd, interviewDest)}`);
-    }
-  } else {
-    logSkip('onboarding-interview.md already in queue');
-  }
-
   // Seed non-credential settings. Auth owns password and signing state.
   if (!opts.dryRun) {
     const configDir = path.join(brainDir, 'config');

package/src/cli/lessons.mjs

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicWrite } from '../core/vault.mjs';
+import { parseLayerFlag, resolveBrainDir } from './agent-dir.mjs';
+import { tickLessons, enqueueSessionReviews } from '../core/lessons.mjs';
+
+export default async function lessons(args) {
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  const [command, ...flags] = remainingArgs;
+  if (!command || flags.includes('--help') || ['--help', '-h'].includes(command)) {
+    console.log('Usage: total-recall lessons tick|session-end|scan [--session ID] [--transcript PATH] [--harness ID] [--interval N] [--hold]\nHooks pass JSON on stdin. Stop queues completed turn ranges; session-end queues the remaining turns. scan reviews locally ingested sessions.');
+    return;
+  }
+  if (!['tick', 'session-end', 'scan'].includes(command)) throw new Error(`Unknown lessons command: ${command}`);
+  const opts = {};
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    if (flag === '--hold') { opts.hold = true; continue; }
+    if (!['--session', '--transcript', '--harness', '--interval', '--event'].includes(flag) || !flags[i + 1]) throw new Error(`Invalid lessons option: ${flag}`);
+    opts[flag.slice(2)] = flags[++i];
+  }
+  const brainDir = resolveBrainDir(layer);
+  if (command === 'scan') {
+    console.log(JSON.stringify(enqueueSessionReviews({ brainDir, interval: opts.interval ? Number(opts.interval) : undefined, hold: opts.hold })));
+    return;
+  }
+  let input = {};
+  if (!process.stdin.isTTY && !opts.session) {
+    const raw = fs.readFileSync(0, 'utf8');
+    if (raw.trim()) input = JSON.parse(raw);
+  }
+  const history = input.entries || input.conversation_history || input.extra?.conversation_history;
+  if (!opts.transcript && !input.transcript_path && Array.isArray(history)) {
+    const id = input.session_id || input.sessionId;
+    if (!id) throw new Error('Lesson hook history requires a session id');
+    const key = crypto.createHash('sha256').update(`${opts.harness || 'unknown'}:${id}`).digest('hex').slice(0, 12);
+    const dir = path.join(brainDir, 'sessions');
+    fs.mkdirSync(dir, { recursive: true });
+    opts.transcript = path.join(dir, `${key}.jsonl`);
+    atomicWrite(opts.transcript, history.map(entry => JSON.stringify(entry)).join('\n') + '\n');
+  }
+  const result = tickLessons({ brainDir, sessionId: opts.session || input.session_id || input.sessionId || input.conversation_id,
+    transcriptPath: opts.transcript || input.transcript_path || input.transcriptPath,
+    harness: opts.harness || 'unknown', turnId: input.turn_id || input.prompt_id,
+    event: command === 'session-end' ? 'SessionEnd' : (opts.event || input.hook_event_name || input.event || 'Stop'),
+    interval: opts.interval ? Number(opts.interval) : undefined, hold: opts.hold });
+  // Hook JSON must not ask the harness to continue, stop, or approve a tool.
+  if (opts.session) console.log(JSON.stringify(result));
+  else console.log('{}');
+}

package/src/cli/memory-plugin.mjs

@@ -26,6 +26,6 @@ export default async function plugin(args = []) {
     const result = await uninstallPlugin(value, { projectRoot: process.cwd(), global: global ? true : undefined });
     console.log(JSON.stringify(result, null, 2));
   } else if (['help', '--help', '-h'].includes(action)) {
-    console.log('Usage: total-recall plugin list|info <id>|install <directory-or-git-url>|remove <id> [--global] [--link]');
+    console.log('Usage: total-recall plugin list|info <id>|install <directory-or-git-url>|remove <id> [--link]');
   } else throw new Error(`Unsupported plugin action '${action}'`);
 }

package/src/cli/plugin/copies.mjs

@@ -1,17 +1,21 @@
 /**
- * Audit and remove per-repository copies of the shared default plugins.
+ * Audit and remove plugin installs inside a repository.
  *
- * One shared plugin folder per machine is the design; copies inside repositories
- * are leftovers from an earlier release that put the nine defaults in every
- * brain. Only copies matching the bundled source can be deleted. The operator
- * can explicitly archive older differing copies to use the shared versions.
+ * Nothing is installed per repository: every plugin lives in the one shared
+ * folder and a repository only switches it on or off. Entries found in a
+ * repository are leftovers. Copies matching the bundled source are deleted;
+ * older differing copies can be archived on request; shadow links (to a plugin
+ * the shared folder installs, or any linked default) are removed as links only.
+ * A repository-only plugin is reported until it is installed in the shared folder.
  */
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { auditProjectPluginCopies } from '../../core/required-plugins.mjs';
-import { globalPluginsDir } from '../../core/plugin-loader.mjs';
-import { recompileAfterPluginMutation, replacementArchiveDir } from '../../core/plugin-store.mjs';
+import { globalPluginsDir, projectPluginsDir, vaultForPluginsDir } from '../../core/plugin-loader.mjs';
+import { recompileAfterPluginMutation, replacementArchiveDir, recordPath } from '../../core/plugin-store.mjs';
+import { findVfsDocumentByPath } from '../../core/vfs-documents.mjs';
+import { deleteVfsDocument } from '../../core/ssss-operation-service.mjs';
 
 export function pluginCopyRows(projectRoot = process.cwd(), { sharedDir = globalPluginsDir() } = {}) {
   const audit = auditProjectPluginCopies(projectRoot, { sharedDir });
@@ -19,7 +23,9 @@ export function pluginCopyRows(projectRoot = process.cwd(), { sharedDir = global
     root: projectRoot,
     sharedDir,
     count: audit.count,
-    removable: audit.copies.filter(copy => copy.edited === false && copy.sharedDir && !copy.linked).map(copy => copy.id),
+    removable: audit.copies.filter(copy => (copy.edited === false && copy.sharedDir && !copy.linked) || copy.shadow).map(copy => copy.id),
+    shadows: audit.copies.filter(copy => copy.shadow).map(copy => copy.id),
+    repoOnly: audit.copies.filter(copy => copy.repoOnly).map(copy => copy.id),
     archivable: audit.copies.filter(copy => copy.stale && copy.edited !== false && !copy.linked).map(copy => copy.id),
     edited: audit.copies.filter(copy => copy.edited === true && copy.stale !== true).map(copy => copy.id),
     stale: audit.copies.filter(copy => copy.stale === true).map(copy => copy.id),
@@ -28,13 +34,49 @@ export function pluginCopyRows(projectRoot = process.cwd(), { sharedDir = global
   };
 }
 
+/**
+ * Install records in this repository's brain for plugins that exist neither in
+ * the repository nor in the shared folder. They describe a repository install
+ * that is gone, so no on/off overlay is lost by removing them.
+ */
+export function orphanRecordIds(projectRoot, { sharedDir = globalPluginsDir() } = {}) {
+  const vaultRoot = vaultForPluginsDir(projectPluginsDir(projectRoot));
+  const dir = path.join(vaultRoot, 'system', 'plugins');
+  let files = [];
+  try { files = fs.readdirSync(dir).filter(name => name.endsWith('.md')); } catch { return []; }
+  return files.map(name => name.slice(0, -3)).filter(id => {
+    if (fs.existsSync(path.join(projectPluginsDir(projectRoot), id))) return false;
+    if (fs.existsSync(path.join(sharedDir, id))) return false;
+    const record = findVfsDocumentByPath(recordPath(id), vaultRoot);
+    return record?.frontmatter?.type === 'plugin_record' && record.frontmatter.source?.kind !== 'shared';
+  });
+}
+
+async function removeOrphanRecords(projectRoot, ids) {
+  const vaultRoot = vaultForPluginsDir(projectPluginsDir(projectRoot));
+  const removed = [];
+  const failed = [];
+  for (const id of ids) {
+    try {
+      await deleteVfsDocument(recordPath(id), { actorRole: 'system', intent: `Remove repository install record ${id}`, vaultRoot });
+      removed.push(id);
+    } catch (error) {
+      failed.push({ id, error: error.message });
+    }
+  }
+  return { removed, failed };
+}
+
 export function removePluginCopies(projectRoot, ids) {
   const removed = [];
   const failed = [];
   for (const id of ids) {
     const dir = path.join(projectRoot, '.agent', 'skills', 'total-recall', 'plugins', id);
     try {
-      fs.rmSync(dir, { recursive: true, force: true });
+      // A link is removed by itself: its target checkout and this repository's
+      // plugin records (including on/off overlays) are left untouched.
+      if (fs.lstatSync(dir).isSymbolicLink()) fs.unlinkSync(dir);
+      else fs.rmSync(dir, { recursive: true, force: true });
       removed.push(id);
     } catch (error) {
       failed.push({ id, error: error.message });
@@ -65,28 +107,36 @@ export async function manageProjectPluginCopies(args = []) {
   const json = args.includes('--json');
   const apply = args.includes('--apply');
   const archiveStale = args.includes('--archive-stale');
+  const dropRepoOnly = args.includes('--drop-repo-only');
   const roots = args.filter(argument => !argument.startsWith('-'));
   const root = roots[0] || process.cwd();
   const report = pluginCopyRows(root);
   if (apply) {
-    report.removal = removePluginCopies(root, report.removable);
+    report.removal = removePluginCopies(root, dropRepoOnly ? [...new Set([...report.removable, ...report.repoOnly])] : report.removable);
+    report.records = await removeOrphanRecords(root, orphanRecordIds(root, { sharedDir: report.sharedDir }));
     if (archiveStale) report.archival = archivePluginCopies(report.copies.filter(copy => report.archivable.includes(copy.id)));
-    if (report.removal.removed.length || report.archival?.archived.length) {
+    if (report.removal.removed.length || report.records.removed.length || report.archival?.archived.length) {
       report.compilation = await recompileAfterPluginMutation(root);
     }
-    if (report.removal.failed.length || report.archival?.failed.length || report.compilation?.ok === false) process.exitCode = 1;
+    if (report.removal.failed.length || report.records.failed.length || report.archival?.failed.length || report.compilation?.ok === false) process.exitCode = 1;
   }
+  if (!apply) report.orphanRecords = orphanRecordIds(root, { sharedDir: report.sharedDir });
   if (json) {
     console.log(JSON.stringify(report, null, 2));
     return;
   }
-  console.log(`\n📦 Per-repository copies of shared plugins in ${report.root}\n`);
+  console.log(`\n📦 Plugin installs inside ${report.root} (all plugins belong in the shared folder)\n`);
+  const records = report.records?.removed || report.orphanRecords || [];
+  if (records.length) console.log(`  ${report.records ? 'Removed' : 'Leftover'} install records for plugins installed nowhere: ${records.join(', ')}${report.records ? '' : ' (re-run with --apply)'}`);
+  if (report.records?.failed.length) console.error(`  Could not remove records: ${report.records.failed.map(row => row.id).join(', ')}`);
   if (report.count === 0) {
     console.log('  None — this repository resolves the shared folder directly.\n');
     return;
   }
   for (const copy of report.copies) {
-    const verdict = copy.linked ? 'linked checkout'
+    const verdict = copy.repoOnly ? `REPOSITORY-ONLY install${copy.target ? ` (link to ${copy.target})` : ''} — install it in the shared folder (plugin install <source>), or delete it with --apply --drop-repo-only`
+      : copy.shadow ? `SHADOW link to ${copy.target} — shadows the shared install`
+      : copy.linked ? 'linked checkout'
       : copy.stale === true ? 'STALE — older than the shared install and shadows it'
       : copy.edited === false ? 'identical to the bundled source'
       : copy.edited === true ? 'DIFFERS from the shared install' : 'no shared install to compare';

package/src/cli/plugin/create.mjs

@@ -1,9 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { validatePluginManifest } from "../../core/plugin-loader.mjs";
+import { validatePluginManifest, isCronExpression } from "../../core/plugin-loader.mjs";
 import { installPlugin } from "../../core/plugin-store.mjs";
-import { parseCron } from "../../core/plugin-cron.mjs";
 
 function toTitleCase(kebab) {
   return kebab
@@ -111,7 +110,7 @@ customElements.define('${id}-panel', ${panelClass});
 }
 
 export async function createPlugin(args = []) {
-  const isGlobal = args.includes("--global") || args.includes("-g");
+  // Every plugin is installed in the shared folder; --global is accepted and changes nothing.
   let withCli = args.includes("--with-cli");
   const withGenerator = args.includes("--with-generator");
   // A card face is bespoke owner code, authored by hand once the plugin's
@@ -212,7 +211,7 @@ export async function createPlugin(args = []) {
 
   if (!id) {
     console.error("❌ Error: Missing plugin id.");
-    console.error("   Usage: total-recall plugin create <id> [--from-skill <path>] [--capability] [--name <name>] [--description <desc>] [--category <cat>] [--global]\n");
+    console.error("   Usage: total-recall plugin create <id> [--from-skill <path>] [--capability] [--name <name>] [--description <desc>] [--category <cat>]\n");
     process.exit(1);
   }
 
@@ -226,7 +225,7 @@ export async function createPlugin(args = []) {
     if (!taskCommand || !/^[a-z][a-z0-9-]*$/.test(taskCommand) || !taskSchedule || !taskIntent) {
       throw new Error('--with-task requires --task-command <subcommand>, --task-schedule "<five-field cron>", and --task-intent <description>');
     }
-    parseCron(taskSchedule);
+    if (!isCronExpression(taskSchedule)) throw new Error(`--task-schedule must be a five-field cron expression, got "${taskSchedule}"`);
   } else if (taskCommand || taskSchedule || taskIntent) {
     throw new Error('--task-* options require --with-task');
   }
@@ -589,7 +588,7 @@ test('every file the manifest references exists', () => {
   // ── Install: a link to the repo, so the repo is what runs ───────────────
   let installed = false;
   if (!skipInstall) {
-    await installPlugin(pluginDir, { link: true, global: isGlobal, projectRoot: process.cwd() });
+    await installPlugin(pluginDir, { link: true, projectRoot: process.cwd() });
     installed = true;
   }
 
@@ -613,7 +612,7 @@ test('every file the manifest references exists', () => {
   if (withCli) {
     console.log(`   CLI Handler: \x1b[32m${path.join(pluginDir, "cli.mjs")}\x1b[0m`);
   }
-  console.log(`   Installed:  ${installed ? `linked into ${isGlobal ? 'the global' : 'this project\'s'} plugins` : 'no (--no-install)'}`);
+  console.log(`   Installed:  ${installed ? `linked into the shared plugin folder` : 'no (--no-install)'}`);
   console.log(`   GitHub:     ${githubUrl || (createGithub ? 'creation failed' : 'not created (re-run with --github, or: gh repo create tr-plugin-' + id + ' --private --source ' + pluginDir + ')')}`);
   console.log(`\nNext steps:`);
   console.log(`   Test:    \x1b[32mcd ${pluginDir} && npm test\x1b[0m`);

package/src/cli/plugin/index.mjs

@@ -27,8 +27,11 @@ Commands:
   list                      Installed plugins (project & global) with source and sharing
   library [--plugin ID]      Installed CLI operation library (--json for agents)
   refresh                   Rebuild installed command inventories and instruction surfaces
-  copies [dir] [--apply]    Audit repository copies of shared defaults. --apply deletes only
-                            bundled matches. Add --archive-stale to preserve older differing copies.
+  copies [dir] [--apply]    Audit repository copies of shared defaults and shadow links. --apply
+                            deletes bundled matches, unlinks shadows (on/off records are kept)
+                            and removes install records of plugins installed nowhere.
+                            Add --archive-stale to preserve older differing copies, and
+                            --drop-repo-only to delete plugins that exist only in the repository.
   replacements [--prune] [--keep N] [--project] [--json]
                             Copies kept by install --replace (default: shared folder). Reports
                             the space; --prune keeps the newest N per plugin (default 1) and
@@ -49,7 +52,8 @@ Commands:
                               <path>              a local directory
                               --link, -l    Symlink a local directory instead of copying
                               --replace     Replace an install, retain previous source and restore on failure
-                              --global, -g  Install for every project on this machine
+                            Every plugin installs into the shared folder for all repositories;
+                            a repository switches it with 'plugin on|off <id>'.
   update [--check] [--json]  Reinstall every plugin whose git repo, mesh peer or source
                             directory moved ahead (--check only reports; also runs hourly
                             in 'update --automatic')
@@ -57,7 +61,7 @@ Commands:
   unshare <id>              Stop offering it
   publish <id>              Publish plugin to the Store and lock release (--no-lock)
   monetize <id>             Configure plugin pricing, period, and payout recipient
-  remove <id>               Uninstall (--global for the machine-wide copy)
+  remove <id>               Uninstall from the shared folder
   license <id> [cmd]        Check or activate plugin license (status, activate, checkout, verify)
   info <id>                 Manifest, provenance, hash and task history
   vendor <source> [dir]     Add a plugin to this project as a brick (default bricks/<id>); the
@@ -80,10 +84,10 @@ Commands:
 
 Examples:
   npx total-recall plugin available --use-case software-development
-  npx total-recall plugin install git-sentinel
-  npx total-recall plugin share git-sentinel
+  npx total-recall plugin install git
+  npx total-recall plugin share git
   npx total-recall plugin peers
-  npx total-recall plugin install peer:mac-mini/git-sentinel
+  npx total-recall plugin install peer:mac-mini/git
   npx total-recall plugin create reading-list --use-case research --with-cli
 `);
 }