total-recall-brain 3.31.2 → 3.32.0

package/src/cli/command.mjs

@@ -1,17 +1,166 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawn } from 'node:child_process';
 import { resolveBrainLayer } from '../core/config.mjs';
+import { isSafeRelativePath, validatePluginManifest } from '../core/plugin-loader.mjs';
+
+const COMMAND_NAME = /^[a-z][a-z0-9-]{0,63}$/;
+
+function safeCommandName(name) {
+  if (!COMMAND_NAME.test(name || '')) throw new Error('Command name must be lowercase kebab-case (1–64 characters)');
+  return name;
+}
+
+/** Generate a composable command from one validated plugin manifest entry. */
+export function generatePluginCommand(pluginDir, name, commandsDir) {
+  safeCommandName(name);
+  const root = fs.realpathSync(pluginDir);
+  const manifestPath = path.join(root, 'plugin.json');
+  if (!fs.statSync(manifestPath).isFile() || fs.lstatSync(manifestPath).isSymbolicLink()) {
+    throw new Error('Plugin manifest must be a regular file');
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const validation = validatePluginManifest(manifest);
+  if (!validation.valid) throw new Error(`Invalid plugin manifest: ${validation.errors.join('; ')}`);
+  const spec = (manifest.commands || []).find((entry) => entry.name === name);
+  if (!spec) throw new Error(`Plugin '${manifest.id}' has no command '${name}'`);
+  if (!isSafeRelativePath(spec.handler) || spec.handler.includes('\\') || !spec.handler.endsWith('.mjs')) {
+    throw new Error(`Command '${name}' needs a safe .mjs handler path`);
+  }
+  const handlerPath = path.resolve(root, spec.handler);
+  const relative = path.relative(root, handlerPath);
+  if (!relative || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)
+      || !fs.statSync(handlerPath).isFile() || fs.realpathSync(handlerPath) !== handlerPath) {
+    throw new Error(`Command '${name}' handler must be a regular file inside the plugin`);
+  }
+  fs.mkdirSync(commandsDir, { recursive: true });
+  const commandPath = path.join(commandsDir, `${name}.mjs`);
+  if (fs.existsSync(commandPath)) throw new Error(`Command '${name}' already exists`);
+  const handlerUrl = pathToFileURL(handlerPath).href;
+  const content = `// Generated from plugin ${manifest.id}; edit the plugin manifest/handler, then regenerate.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const name = ${JSON.stringify(name)};
+const description = ${JSON.stringify(spec.description || '')};
+const handlerUrl = ${JSON.stringify(handlerUrl)};
+const backgroundAllowed = ${spec.background === true};
+
+export async function run(argv = process.argv, direct = false) {
+  const args = argv.slice(direct ? 2 : 3);
+  const json = args.includes('--json');
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: total-recall ' + name + ' [args…] [--json]' + (backgroundAllowed ? ' [--background]' : '') + '\\n\\n' + description);
+    return;
+  }
+  try {
+    if (args.includes('--background')) {
+      if (!backgroundAllowed) throw Object.assign(new Error('Background execution is not enabled for this command'), { exitCode: 2 });
+      const reports = path.join(path.dirname(fileURLToPath(import.meta.url)), 'reports');
+      fs.mkdirSync(reports, { recursive: true, mode: 0o700 });
+      const report = path.join(reports, name + '-' + crypto.randomUUID() + '.log');
+      const fd = fs.openSync(report, 'wx', 0o600);
+      const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...args.filter((a) => a !== '--background')], {
+        detached: true, stdio: ['ignore', fd, fd]
+      });
+      fs.closeSync(fd);
+      child.unref();
+      const status = { ok: true, pid: child.pid, report };
+      if (json) console.log(JSON.stringify(status));
+      else console.log('Started ' + name + ' in background (pid ' + child.pid + '); report: ' + report);
+      return status;
+    }
+    const handler = await import(handlerUrl);
+    const entry = handler.run || handler.default;
+    if (typeof entry !== 'function') throw new Error('Plugin command handler must export run() or default function');
+    const handlerArgs = args.filter((arg) => arg !== '--json');
+    const result = await entry(handler.run ? [process.execPath, 'total-recall', name, ...handlerArgs] : handlerArgs);
+    const exitCode = Number.isInteger(result?.exitCode) ? result.exitCode : 0;
+    if (json) console.log(JSON.stringify({ ok: exitCode === 0, exit_code: exitCode, result: result?.data ?? result ?? null }));
+    process.exitCode = exitCode;
+    return result;
+  } catch (error) {
+    const exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+    if (json) console.log(JSON.stringify({ ok: false, exit_code: exitCode, error: error.message }));
+    else console.error(error.message);
+    process.exitCode = exitCode;
+  }
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await run(process.argv, true);
+}
+`;
+  fs.writeFileSync(commandPath, content, { encoding: 'utf8', flag: 'wx', mode: 0o644 });
+  return commandPath;
+}
+
+/**
+ * Generate `total-recall <name> config|<collection>|detect|init` for a layered
+ * skill deployed in the repo that owns `commandsDir` (<repo>/.agent/commands).
+ * The wrapper holds no config logic: it delegates to the running Total Recall
+ * CLI, so the layer contract in the skill core stays the only source of truth.
+ */
+export function generateSkillConfigCommand(skillId, name, commandsDir) {
+  safeCommandName(name);
+  safeCommandName(skillId);
+  const repoRoot = path.resolve(commandsDir, '..', '..');
+  const schemaPath = path.join(repoRoot, '.agent', 'skills', skillId, 'core', 'config.schema.json');
+  if (!fs.existsSync(schemaPath) || !fs.statSync(schemaPath).isFile()) {
+    throw new Error(`Skill '${skillId}' in ${repoRoot} has no core/config.schema.json; deploy the layered skill first`);
+  }
+  fs.mkdirSync(commandsDir, { recursive: true });
+  const commandPath = path.join(commandsDir, `${name}.mjs`);
+  if (fs.existsSync(commandPath)) throw new Error(`Command '${name}' already exists`);
+  const fallbackModule = pathToFileURL(path.join(path.dirname(fileURLToPath(import.meta.url)), 'skill-config.mjs')).href;
+  const content = `// Generated repo-layer config command for skill ${skillId}; the contract is .agent/skills/${skillId}/core/config.schema.json.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const skillId = ${JSON.stringify(skillId)};
+const name = ${JSON.stringify(name)};
+const fallbackModule = ${JSON.stringify(fallbackModule)};
+
+// Prefer the Total Recall install that is running this command, so upgrades apply.
+function configModule() {
+  try {
+    const bin = fs.realpathSync(process.argv[1]);
+    const candidate = path.join(path.dirname(path.dirname(bin)), 'src', 'cli', 'skill-config.mjs');
+    if (path.basename(bin) === 'total-recall.mjs' && fs.existsSync(candidate)) return pathToFileURL(candidate).href;
+  } catch { /* fall back to the generating install */ }
+  return fallbackModule;
+}
+
+export async function run(argv = process.argv) {
+  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const { runSkillConfig } = await import(configModule());
+  return runSkillConfig(skillId, argv.slice(3), { repoRoot, prefix: 'total-recall ' + name });
+}
+`;
+  fs.writeFileSync(commandPath, content, { encoding: 'utf8', flag: 'wx', mode: 0o644 });
+  return commandPath;
+}
 
 function printHelp() {
   console.log(`
   total-recall command — Manage custom composable CLI commands
 
   Usage:
-    total-recall command create <name> "<code>" [--global]   Create a new custom CLI command
+    total-recall command create <name> "<code>" [--global] [--description "<when to use>"] [--risk <class>]
+                                                             Create a custom CLI command (listed in instruction surfaces)
+    total-recall command create <name> --from-plugin <dir>   Generate from a plugin manifest
+    total-recall command create <name> --config-for-skill <id>
+                                                             Generate repo-layer config verbs for a
+                                                             layered skill deployed in this repo
     total-recall command read <name> [--global]              Read the code of a custom CLI command
     total-recall command update <name> "<code>" [--global]   Update an existing custom CLI command
     total-recall command remove <name> [--global]            Remove a custom CLI command
-    total-recall command list [--global]                     List custom CLI commands
+    total-recall command list [--global] [--json]            List custom CLI commands
 
   Examples:
     npx total-recall command create hello "console.log('Hello from the brain!');"
@@ -49,9 +198,66 @@ export async function run(argv = []) {
   return commandCmd(args);
 }
 
+/**
+ * Built-in verbs resolve before custom commands (bin/total-recall.mjs), so a
+ * custom command with a built-in name could never run. Read the names from the
+ * dispatcher itself so this list cannot drift.
+ */
+export function builtinCommandNames() {
+  try {
+    const bin = fs.readFileSync(new URL('../../bin/total-recall.mjs', import.meta.url), 'utf8');
+    const block = bin.match(/^const COMMANDS = \{([\s\S]*?)^\};/m)?.[1] || '';
+    return new Set([...block.matchAll(/^\s+'?([a-z][a-z0-9-]*)'?\s*:/gm)].map((m) => m[1]));
+  } catch {
+    return new Set();
+  }
+}
+
+const RISKS = new Set(['read', 'write', 'money', 'dns-cert', 'production-deploy', 'secret-revoke']);
+
+/** Pull `--flag <value>` pairs out of argv so positional parsing is unaffected. */
+function takeOption(list, flag) {
+  const i = list.indexOf(flag);
+  if (i === -1) return { list, value: undefined };
+  return { list: [...list.slice(0, i), ...list.slice(i + 2)], value: list[i + 1] };
+}
+
+function headerTags(description, risk) {
+  const one = (v) => String(v).replace(/[\r\n]+/g, ' ').trim();
+  return (description ? `// @description ${one(description)}\n` : '') + (risk ? `// @risk ${risk}\n` : '');
+}
+
+function existingTag(file, key) {
+  try { return fs.readFileSync(file, 'utf8').match(new RegExp(`^// @${key} (.+)$`, 'm'))?.[1] || undefined; } catch { return undefined; }
+}
+
+/**
+ * Composable instructions: the surfaces list every command, so any change to
+ * the command set recompiles them (project layer, or every project for global).
+ */
+function recompileSurfaces(isGlobal) {
+  if (process.env.TR_COMMAND_NO_COMPILE === '1' || !process.argv[1]) return;
+  try {
+    const child = spawn(process.execPath, [process.argv[1], 'compile', isGlobal ? '--global' : '--project'], { detached: true, stdio: 'ignore' });
+    child.unref();
+    console.log('  ⏳ Instruction surfaces recompiling in the background (command list updated).');
+  } catch (error) {
+    console.warn(`  ⚠️  Command saved, but surface recompile failed to start: ${error.message}`);
+  }
+}
+
 export default async function commandCmd(rawArgs = []) {
   const isGlobal = rawArgs.includes('--global') || rawArgs.includes('-g');
-  const cleanArgs = rawArgs.filter(a => a !== '--global' && a !== '-g');
+  const asJson = rawArgs.includes('--json');
+  let cleanArgs = rawArgs.filter(a => a !== '--global' && a !== '-g' && a !== '--json');
+  let description; let risk;
+  ({ list: cleanArgs, value: description } = takeOption(cleanArgs, '--description'));
+  ({ list: cleanArgs, value: risk } = takeOption(cleanArgs, '--risk'));
+  if (risk !== undefined && !RISKS.has(risk)) {
+    console.error(`Error: --risk must be one of ${[...RISKS].join(', ')}`);
+    process.exitCode = 2;
+    return;
+  }
 
   const action = cleanArgs[0];
   const name = cleanArgs[1];
@@ -67,9 +273,50 @@ export default async function commandCmd(rawArgs = []) {
     process.exit(1);
   }
 
+  if (name) {
+    try { safeCommandName(name); }
+    catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 2; return; }
+  }
+
   const commandsDir = resolveTargetDir(isGlobal);
 
   if (action === 'create') {
+    if (builtinCommandNames().has(name)) {
+      console.error(`Error: '${name}' is a built-in Total Recall command; a custom command with that name could never run. Choose another name.`);
+      process.exitCode = 2;
+      return;
+    }
+    const otherDir = resolveTargetDir(!isGlobal);
+    if (path.resolve(otherDir) !== path.resolve(commandsDir) && fs.existsSync(path.join(otherDir, `${name}.mjs`))) {
+      console.warn(`  ⚠️  A ${isGlobal ? 'project' : 'global'} command '${name}' already exists (${otherDir}); the project one runs first here.`);
+    }
+    const forSkill = cleanArgs.indexOf('--config-for-skill');
+    if (forSkill !== -1) {
+      try {
+        if (isGlobal) throw new Error('Repo-layer config commands belong to one repository; omit --global');
+        if (!cleanArgs[forSkill + 1]) throw new Error('Missing skill id after --config-for-skill');
+        const commandPath = generateSkillConfigCommand(cleanArgs[forSkill + 1], name, commandsDir);
+        console.log(`✔ Generated npx total-recall ${name} config|detect|init; saved to: ${commandPath}`);
+        recompileSurfaces(isGlobal);
+      } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+    const fromPlugin = cleanArgs.indexOf('--from-plugin');
+    if (fromPlugin !== -1) {
+      try {
+        if (!cleanArgs[fromPlugin + 1]) throw new Error('Missing plugin directory after --from-plugin');
+        const commandPath = generatePluginCommand(cleanArgs[fromPlugin + 1], name, commandsDir);
+        console.log(`✔ Generated npx total-recall ${name} from plugin; saved to: ${commandPath}`);
+        recompileSurfaces(isGlobal);
+      } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
     const code = cleanArgs[2];
     if (!code) {
       console.error(`Error: Missing code snippet for the command.`);
@@ -82,10 +329,15 @@ export default async function commandCmd(rawArgs = []) {
     }
 
     const commandPath = path.join(commandsDir, `${name}.mjs`);
+    if (fs.existsSync(commandPath)) {
+      console.error(`Error: Custom command '${name}' already exists.`);
+      process.exitCode = 1;
+      return;
+    }
     
     // Wrap code in an exported run/default function for composable CLI execution
     const fileContent = `// Auto-generated custom CLI command: ${name}
-export async function run(argv = []) {
+${headerTags(description, risk)}export async function run(argv = []) {
   const args = Array.isArray(argv) ? argv.slice(3) : [];
   ${code}
 }
@@ -97,6 +349,8 @@ export default async function (args = []) {
     fs.writeFileSync(commandPath, fileContent, 'utf8');
     console.log(`\x1b[32m✔ Successfully created custom command: \x1b[1mnpx total-recall ${name}\x1b[0m`);
     console.log(`  Saved to: ${commandPath}`);
+    if (!description) console.log('  Tip: add --description "<when to use it>" so the instruction surfaces say when to use this command.');
+    recompileSurfaces(isGlobal);
   } else if (action === 'read') {
     const commandPath = path.join(commandsDir, `${name}.mjs`);
     if (fs.existsSync(commandPath)) {
@@ -119,8 +373,11 @@ export default async function (args = []) {
       process.exit(1);
     }
 
+    // Keep the declared description/risk unless the update replaces them.
+    const keptDescription = description ?? existingTag(commandPath, 'description');
+    const keptRisk = risk ?? existingTag(commandPath, 'risk');
     const fileContent = `// Auto-generated custom CLI command: ${name}
-export async function run(argv = []) {
+${headerTags(keptDescription, keptRisk)}export async function run(argv = []) {
   const args = Array.isArray(argv) ? argv.slice(3) : [];
   ${code}
 }
@@ -132,6 +389,7 @@ export default async function (args = []) {
     fs.writeFileSync(commandPath, fileContent, 'utf8');
     console.log(`\x1b[32m✔ Successfully updated custom command: \x1b[1m${name}\x1b[0m`);
     console.log(`  Saved to: ${commandPath}`);
+    recompileSurfaces(isGlobal);
   } else if (action === 'list') {
     const targets = isGlobal 
       ? [{ label: 'Global', dir: resolveTargetDir(true) }]
@@ -140,6 +398,11 @@ export default async function (args = []) {
           { label: 'Global', dir: resolveTargetDir(true) }
         ];
 
+    if (asJson) {
+      const { listSurfaceCommands } = await import('../core/command-surface.mjs');
+      console.log(JSON.stringify(listSurfaceCommands(targets.map((t) => ({ scope: t.label.toLowerCase(), dir: t.dir })))));
+      return;
+    }
     let foundAny = false;
     for (const t of targets) {
       if (fs.existsSync(t.dir)) {
@@ -161,6 +424,7 @@ export default async function (args = []) {
     if (fs.existsSync(commandPath)) {
       fs.unlinkSync(commandPath);
       console.log(`\x1b[32m✔ Successfully removed custom command: \x1b[1m${name}\x1b[0m`);
+      recompileSurfaces(isGlobal);
     } else {
       console.error(`Error: Custom command '${name}' does not exist.`);
       process.exit(1);

package/src/cli/connect.mjs

@@ -10,7 +10,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Resolve templates dir relative to this file (src/cli/ → ../../templates/)
 const TEMPLATES_DIR = path.resolve(__dirname, '..', '..', 'templates');
 
-const CLIENTS = {
+export const CLIENTS = {
   vscode: {
     label: 'VS Code Copilot',
     mode: 'file',

package/src/cli/daemon.mjs

@@ -164,8 +164,8 @@ function directStart() {
   }
 }
 
-function directStop() {
-  const stopped = stopDaemon();
+async function directStop() {
+  const stopped = await stopDaemon();
   if (stopped) {
     console.error('  ✅ Daemon stopped');
   } else {
@@ -215,7 +215,7 @@ export default async function daemon(args) {
     case 'stop':
       if (useSystemd) systemdStop();
       else if (useLaunchd) launchctlStop();
-      else directStop();
+      else await directStop();
       break;
     case 'status':
       if (useSystemd) systemdStatus();

package/src/cli/init.mjs

@@ -30,7 +30,9 @@ import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { exec, spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { projectSkillsForScope, detectActiveSkillTargets } from './skill-projection.mjs';
+import { ensureRepoExpert } from './repo-expert-generate.mjs';
 import { writeFileSecure } from '../core/secure-file.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -262,6 +264,9 @@ export default async function init(args) {
   }
 
   for (const skill of skillsToSeed) {
+    // A repository expert contains project facts and must never be copied from
+    // the global brain or package scaffold into a different checkout.
+    if (isProject && skill === 'repo-expert') continue;
     let skillSrc = path.join(scaffoldSkillsDir, skill);
 
     // For ssss: prefer the npm-installed @ssss/cli package over scaffold
@@ -601,6 +606,17 @@ export default async function init(args) {
   logStep('3.6/4', 'Ensuring openwiki is present');
   await ensureOpenWiki(brainDir, isProject, opts.dryRun);
 
+  if (isProject) {
+    logStep('3.6/4', 'Ensuring repository-specific expert');
+    try {
+      const expert = ensureRepoExpert(cwd, { dryRun: opts.dryRun });
+      logOk(`repo-expert ${expert.action}: ${path.relative(cwd, expert.destFile)}`);
+    } catch (err) {
+      logWarn(`Project initialization stopped: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
   // ── Step 3.7: Project skills into the IDEs in use ──
   // Scope matches the brain: `init --project` projects PROJECT skills into the
   // repo's IDE skill dirs for IDEs actually used here (.claude/, .agents/, or
@@ -629,6 +645,7 @@ export default async function init(args) {
           logOk(`${t.label}: ${n} skill(s) → ${path.relative(cwd, t.destDir) || t.destDir}/`);
         }
         log(`  Discoverable skills: ${skills.map(s => s.name).join(', ')}`);
+        if (isProject) await connectDetectedClients(wired);
         if (available.length > 0) {
           log(`  Also available (opt-in): ${available.map(t => t.clients.join('/')).join(', ')} — \`npx total-recall connect <ide>\``);
         }
@@ -691,6 +708,11 @@ export default async function init(args) {
       needsBootstrap = true;
     }
 
+    if (isProject && !brainCfg.project_id) {
+      brainCfg.project_id = randomUUID();
+      needsBootstrap = true;
+    }
+
     if (needsBootstrap) {
       try {
         const { issueKey } = await import('../server/keys.mjs');
@@ -699,6 +721,9 @@ export default async function init(args) {
         brainCfg.token = brainCfg.token || keyData.token;
         writeFileSecure(brainJsonPath, JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
         logOk(`Bootstrap configuration successfully generated and pre-authorized at ${brainCfg.url}`);
+        if (brainCfg.project_id) {
+          logOk(`Assigned project UUID ${brainCfg.project_id} to project brain`);
+        }
       } catch (err) {
         logWarn(`Could not auto-generate bootstrap developer key: ${err.message}`);
       }
@@ -859,7 +884,14 @@ export default async function init(args) {
       }
       const projectName = path.basename(cwd);
       const existingIdx = registry.findIndex(p => p.path === cwd);
+      // brainCfg is block-scoped to the bootstrap branch above; re-read the
+      // persisted brain.json so the project UUID reaches the registry.
+      let projectId;
+      try {
+        projectId = JSON.parse(fs.readFileSync(path.join(brainDir, 'config', 'brain.json'), 'utf8')).project_id;
+      } catch { projectId = undefined; }
       const entry = {
+        project_id: projectId || undefined,
         name: projectName,
         path: cwd,
         brainDir: brainDir,
@@ -921,3 +953,25 @@ export default async function init(args) {
 
   process.exit(0);
 }
+
+/**
+ * Register every IDE detected as in use as a connected client, so step 4's
+ * compile writes that IDE's instruction shim (CLAUDE.md, AGENTS.md, GEMINI.md…).
+ * Projecting skills alone left new repos without the global rules.
+ */
+export async function connectDetectedClients(wired, { connectFn } = {}) {
+  const { default: connect, CLIENTS } = await import('./connect.mjs');
+  const run = connectFn || connect;
+  const connected = [];
+  for (const target of wired) {
+    const client = (target.clients || []).find((c) => CLIENTS[c]);
+    if (!client || connected.includes(client)) continue;
+    try {
+      await run([client]);
+      connected.push(client);
+    } catch (err) {
+      logWarn(`Could not connect ${client}: ${err.message} — run \`npx total-recall connect ${client}\``);
+    }
+  }
+  return connected;
+}

package/src/cli/plugin/create.mjs

@@ -116,10 +116,10 @@ export async function createPlugin(args = []) {
   const pluginDesc = description || skillFrontmatter.description || `${pluginName} extension for Total Recall AI OS`;
 
   const manifest = {
-    $schema: "https://github.com/total-recall/total-recall/blob/main/metadata.plugin.schema.json",
+    $schema: "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
     id,
     name: pluginName,
-    version: "1.0.0",
+    version: "0.1.0",
     description: pluginDesc,
     license: "MIT"
   };
@@ -145,8 +145,7 @@ export async function createPlugin(args = []) {
       command: id,
       handler: "./cli.mjs",
       subcommands: [
-        { name: "status", description: `Show ${pluginName} status` },
-        { name: "run", description: `Execute ${pluginName} primary task` }
+        { name: "status", description: `Show which ${pluginName} subcommands are implemented` }
       ]
     };
 
@@ -155,16 +154,27 @@ export async function createPlugin(args = []) {
  * ${pluginName} CLI Handler
  * Executed via: npx total-recall ${id} <subcommand>
  */
+// Scaffold: report honestly what exists. Add each real subcommand to
+// IMPLEMENTED and to plugin.json "cli.subcommands" as it is built.
+const IMPLEMENTED = {};
+
 export async function run(argv = []) {
   const args = Array.isArray(argv) ? argv.slice(3) : [];
   const sub = args[0] || "status";
-  
+  const json = args.includes("--json");
+
   if (sub === "status") {
-    console.log(\`✅ ${pluginName} v1.0.0 is operational.\`);
+    const status = { plugin: ${JSON.stringify(id)}, implemented: Object.keys(IMPLEMENTED) };
+    if (json) console.log(JSON.stringify(status));
+    else console.log(status.implemented.length
+      ? \`${pluginName}: implemented subcommands: \${status.implemented.join(", ")}\`
+      : \`${pluginName}: scaffold only — no subcommands implemented yet.\`);
     return;
   }
-  
-  console.log(\`${pluginName}: executed subcommand "\${sub}" with args:\`, args.slice(1));
+  if (IMPLEMENTED[sub]) return IMPLEMENTED[sub](args.slice(1));
+
+  console.error(\`${pluginName}: "\${sub}" is not implemented.\`);
+  process.exitCode = 2;
 }
 export default run;
 `;
@@ -204,7 +214,7 @@ export default run;
     const skillContent = `---
 name: ${id}
 description: "${pluginDesc}"
-version: 1.0.0
+version: 0.1.0
 ---
 
 # ${pluginName}
@@ -284,7 +294,7 @@ export default generateContext;
     "## Features",
     "",
     `- **Identifier**: \`${id}\``,
-    "- **Version**: 1.0.0"
+    "- **Version**: 0.1.0"
   ];
   if (useCases.length) lines.push(`- **Use cases**: ${useCases.join(", ")}`);
   if (category) lines.push(`- **SSSS Category**: \`${category}\``);

package/src/cli/repo-expert-generate.mjs

@@ -13,6 +13,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 
+const SKIP_SCAN_DIRS = new Set([
+  '.agent', '.agents', '.claude', '.git', '.venv', 'node_modules', 'dist',
+  'build', 'coverage', '__pycache__', 'vault', 'logs', 'vendor',
+]);
+
 /**
  * Scan a repo and return structured architecture data.
  */
@@ -83,7 +88,7 @@ export function scanRepo(repoRoot) {
     try {
       const entries = fs.readdirSync(dir, { withFileTypes: true });
       for (const entry of entries) {
-        if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build') continue;
+        if (entry.name.startsWith('.') || SKIP_SCAN_DIRS.has(entry.name)) continue;
         const full = path.join(dir, entry.name);
         if (entry.isDirectory()) {
           walkForExtensions(full, depth + 1);
@@ -119,8 +124,7 @@ export function scanRepo(repoRoot) {
     try {
       const entries = fs.readdirSync(dir, { withFileTypes: true });
       for (const entry of entries) {
-        if (entry.name.startsWith('.') && entry.name !== '.agent' && entry.name !== '.agents') continue;
-        if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build' || entry.name === '.git') continue;
+        if (entry.name.startsWith('.') || SKIP_SCAN_DIRS.has(entry.name)) continue;
         const full = path.join(dir, entry.name);
         if (entry.isDirectory()) {
           const childCount = countChildren(full);
@@ -330,6 +334,7 @@ export function generateSkillMd(scan, repoRoot) {
   lines.push('  structure, and runtime topology. MANDATORY: You MUST read the full SKILL.md');
   lines.push('  file before executing.');
   lines.push('repo_scoped: true');
+  lines.push(`repository_id: ${JSON.stringify(scan.name || path.basename(path.resolve(repoRoot)))}`);
   lines.push(`generated_at: ${new Date().toISOString()}`);
   // Record the repo by name, never by absolute path. SKILL.md is committed, so
   // an absolute root bakes the generating machine's home directory into the
@@ -520,6 +525,35 @@ export function generateRepoExpert(repoRoot, opts = {}) {
   };
 }
 
+/** Preserve a local expert and reject one that identifies another repository. */
+export function ensureRepoExpert(repoRoot, opts = {}) {
+  const root = path.resolve(repoRoot);
+  const destFile = path.join(root, '.agent', 'skills', 'repo-expert', 'SKILL.md');
+  let repositoryId = path.basename(root);
+  try {
+    repositoryId = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name || repositoryId;
+  } catch { /* non-Node repositories use the checkout name */ }
+
+  if (fs.existsSync(destFile)) {
+    const content = fs.readFileSync(destFile, 'utf8');
+    const header = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] || '';
+    const scoped = /^repo_scoped:\s*true\s*$/m.test(header);
+    const id = header.match(/^repository_id:\s*(.+)\s*$/m)?.[1]?.trim();
+    const generatedFrom = header.match(/^generated_from:\s*(.+)\s*$/m)?.[1]?.trim();
+    const parsedId = id?.replace(/^["']|["']$/g, '');
+    const parsedFrom = generatedFrom?.replace(/^["']|["']$/g, '');
+    if (!scoped || (parsedId ? parsedId !== repositoryId :
+      !parsedFrom || parsedFrom !== path.basename(root))) {
+      throw new Error(`Existing repo-expert does not match ${repositoryId}: ${destFile}`);
+    }
+    return { action: 'existing', destFile, repositoryId };
+  }
+
+  if (opts.dryRun) return { action: 'would-generate', destFile, repositoryId };
+  generateRepoExpert(root);
+  return { action: 'generated', destFile, repositoryId };
+}
+
 /**
  * CLI handler for `npx total-recall skill generate-expert`
  */