total-recall-brain 3.31.0 → 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/config.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'yaml';
 import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
+import { writeFileSecure } from '../core/secure-file.mjs';
 
 // Pre-defined mapping of known settings
 const KEY_MAP = {
@@ -224,7 +225,7 @@ export default async function configCommand(args) {
       if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });
       }
-      fs.writeFileSync(targetPath, yaml.stringify(targetObj), { encoding: 'utf8', mode: 0o600 });
+      writeFileSecure(targetPath, yaml.stringify(targetObj), { encoding: 'utf8', mode: 0o600 });
 
       console.log(`\n  ✅ Success! Config key "${key}" ${layerLabel} set to: ${JSON.stringify(parsedValue)}`);
       console.log(`  📍 Saved in: ${targetPath}\n`);

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/deploy-ui.mjs

@@ -19,6 +19,7 @@ import os from 'node:os';
 import path from 'node:path';
 import bcrypt from 'bcrypt';
 import yaml from 'yaml';
+import { writeFileSecure } from '../core/secure-file.mjs';
 import { BCRYPT_COST } from '../server/auth.mjs';
 
 
@@ -175,7 +176,7 @@ export function startDeployUI(port = 3001) {
               if (opts.cloudRegion) current['cfg-cloud-region'] = opts.cloudRegion;
               if (opts.installGlobal !== undefined) current['installGlobal'] = opts.installGlobal;
               if (opts.projectPaths) current['projectPaths'] = opts.projectPaths;
-              fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+              writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
 
             } catch (e) {
               console.error('Failed to auto-persist install options on disk:', e);
@@ -572,7 +573,7 @@ export function startDeployUI(port = 3001) {
             }
 
             const updated = { ...current, ...data };
-            fs.writeFileSync(configFile, JSON.stringify(updated, null, 2), { encoding: 'utf8', mode: 0o600 });
+            writeFileSecure(configFile, JSON.stringify(updated, null, 2), { encoding: 'utf8', mode: 0o600 });
             syncInstallOptionsFromDisk();
 
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1114,7 +1115,7 @@ export function startDeployUI(port = 3001) {
             }
             current['cfg-github-token'] = token;
             current['backupRepo'] = backupUrl;
-            fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+            writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
 
             log('✅ Encryption keys and tokens written.');
 
@@ -1735,7 +1736,7 @@ console.log("REMOTE_PASS_OK");
       if (_installOptions.dashboardPassword) {
         current['cfg-dashboard-password'] = _installOptions.dashboardPassword;
       }
-      fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+      writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
     } catch (e) {
       console.error('Failed to auto-persist remote install options on disk:', e);
     }

package/src/cli/deploy.mjs

@@ -43,6 +43,7 @@ import yaml from 'yaml';
 import bcrypt from 'bcrypt';
 import crypto from 'node:crypto';
 import { BCRYPT_COST } from '../server/auth.mjs';
+import { writeFileSecure } from '../core/secure-file.mjs';
 
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -407,7 +408,7 @@ function hardenSecurityConfig(dryRun, dashboardPassword = null) {
     log('  🔑 Dashboard credentials left unconfigured. You will set your admin password on first dashboard access.');
   }
 
-  fs.writeFileSync(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
+  writeFileSecure(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
   logOk('Security config hardened: HTTPS required, Express bound to localhost, no public health, no legacy local PAT');
 }
 
@@ -1095,7 +1096,7 @@ export default async function deploy(args) {
           if (wizardOpts.dashboardPassword) {
             current['cfg-dashboard-password'] = wizardOpts.dashboardPassword;
           }
-          fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+          writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
         } catch (e) {
           console.error('Failed to auto-persist cloud install options on disk:', e);
         }

package/src/cli/init.mjs

@@ -30,7 +30,10 @@ 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));
 const ROOT = path.join(__dirname, '..', '..');
@@ -261,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
@@ -408,10 +414,10 @@ export default async function init(args) {
       }
 
       if (!config.dashboard.password_hash) {
-        fs.writeFileSync(securityPath, yaml.stringify(config), { encoding: "utf8", mode: 0o600 });
+        writeFileSecure(securityPath, yaml.stringify(config), { encoding: "utf8", mode: 0o600 });
         passwordMessage = "\n  🔑 Dashboard Access: Unconfigured\n     (You will be prompted to set your password upon first browser access)";
       } else {
-        fs.writeFileSync(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
+        writeFileSecure(securityPath, yaml.stringify(config), { encoding: 'utf8', mode: 0o600 });
         passwordMessage = '\n  🔑 Dashboard credentials preserved (custom password hash already configured)';
       }
     } catch (err) {
@@ -586,7 +592,7 @@ export default async function init(args) {
       current['cfg-health-url'] = 'http://localhost:3000/health';
     }
 
-    fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+    writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
     logOk('UI deploy configuration persisted to wizard-config.json!');
   }
 
@@ -600,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
@@ -628,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>\``);
         }
@@ -670,7 +688,7 @@ export default async function init(args) {
     fs.mkdirSync(cfgDir, { recursive: true });
     const brainCfg = { url: opts.brain };
     if (opts.token) brainCfg.token = opts.token;
-    fs.writeFileSync(path.join(cfgDir, 'brain.json'), JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
+    writeFileSecure(path.join(cfgDir, 'brain.json'), JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
     logOk(`Registered brain at ${opts.brain}. Run \`npx total-recall sync\` to pull instructions.`);
   } else {
     // Zero-config bootstrap: auto-generate localhost brain.json and valid Developer PAT out-of-the-box
@@ -690,14 +708,22 @@ 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');
         const keyData = issueKey('Default Local Developer Key', { scopes: ['*'] });
         brainCfg.url = brainCfg.url || 'http://localhost:3000';
         brainCfg.token = brainCfg.token || keyData.token;
-        fs.writeFileSync(brainJsonPath, JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
+        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}`);
       }
@@ -786,7 +812,7 @@ export default async function init(args) {
           current['cfg-dash-url'] = `${tunnelUrl}/`;
           current['cfg-health-url'] = `${tunnelUrl}/health`;
           
-          fs.writeFileSync(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
+          writeFileSecure(configFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 });
           logOk('Registered Quick Tunnel URL in wizard-config.json!');
           dashboardUrl = `${tunnelUrl}/`;
         } else {
@@ -858,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,
@@ -920,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;
+}