total-recall-brain 3.39.4 → 3.39.7

package/docs/reference/cli-reference.md

@@ -128,8 +128,9 @@ action and the largest rules; `draft --out policy.json` scaffolds the policy wit
 each rule's original text; shorten the directives by hand (keep every operative
 constraint), narrow `actions`, or exclude locally with `enabled:false` plus a
 `reason`; `apply policy.json` validates hashes and merges into the single
-`context:policy` decision; `verify` exits 1 on stale or orphan curation or an
-action capsule over budget; `prune [--apply] [--archive]` drops stale entries and
+`context:policy` decision; `verify [--json]` exits 1 on stale or orphan curation or
+an action capsule over budget; `prune [--apply] [--archive] [--json]` drops stale
+entries and
 lists expired, superseded or duplicate rules. Originals are never modified.
 
 ### `recall`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.39.4",
+  "version": "3.39.7",
   "description": "Portable SSSS memory, local retrieval and task instructions with explicit plugin loading.",
   "type": "module",
   "bin": {

package/scaffold/.agent/skills/total-recall/SKILL.md

@@ -19,7 +19,6 @@ Total Recall is working memory and the operation toolbox. Before decisions about
 | Remember, recall, context, compile, dream, proposals, vault | Core portable memory and SSSS contracts | [Memory and instructions](references/memory.md) |
 | Credentials, passwords, sessions, passkeys, PATs, encryption, rotation, projections, sync | `total-recall auth --help`; `auth secret --help` | [Auth and secrets](references/auth.md) |
 | Documentation hubs and graph ingestion | `total-recall openwiki --help`; `openwiki hubs --json` | [OpenWiki](references/openwiki.md) |
-| Accounts, buyers, records, branding, portable CRM instances | `total-recall crm status`; `crm menu` | [CRM](references/crm.md) |
 | Nodes, access, enrollment, control server, presence, dispatch | `total-recall mesh --help` | [Mesh](references/mesh.md) |
 | Install, author, configure and run plugins | `total-recall plugin --help`; `plugin list --json` | [Plugins](references/plugins.md) |
 | Machines, networks, fleet audits and verified hardening | `total-recall security status --json`; owning plugin skill | [Security](references/security.md) |

package/scaffold/.agent/skills/total-recall/plugins/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-auth",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "White-label Total Recall auth plugin: Passkey biometric FIDO2 and Google OAuth2 authentication.",
   "type": "module",
   "main": "cli.mjs",

package/scaffold/.agent/skills/total-recall/plugins/auth/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "auth",
   "name": "Auth & Secrets",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Hardware WebAuthn biometric FIDO2 passkeys, OAuth session security, and access control.",
   "author": "Total Recall contributors",
   "license": "MIT",

package/scaffold/.agent/skills/total-recall/plugins/auth/src/secrets-sync.mjs

@@ -7,17 +7,20 @@ import { resolveSecretsPath, loadSecrets, saveSecrets, ensureMeta, appendAudit,
 
 const REQUEST_TIMEOUT_MS = 10_000;
 
-function serverPort() {
-  const value = Number(process.env.TR_SERVER_PORT || process.env.PORT || 3000);
-  return Number.isInteger(value) && value > 0 && value <= 65535 ? value : 3000;
+function serverPort(override) {
+  // The leader's port is whatever it advertised on the mesh. Assuming the local
+  // default made sync fail with "fetch failed" against a leader that was up and
+  // reachable on a different port (the cloud brain serves on 3900, not 3000).
+  const candidate = Number(override ?? process.env.TR_SERVER_PORT ?? process.env.PORT ?? 3000);
+  return Number.isInteger(candidate) && candidate > 0 && candidate <= 65535 ? candidate : 3000;
 }
 
-function meshUrl(ip, route) {
+function meshUrl(ip, route, port) {
   const octets = String(ip || '').split('.').map(Number);
   if (octets.length !== 4 || octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255) || octets[0] !== 100 || octets[1] < 64 || octets[1] > 127) {
     throw new Error('Leader IP is outside the Tailscale CGNAT range');
   }
-  return `http://${ip}:${serverPort()}${route}`;
+  return `http://${ip}:${serverPort(port)}${route}`;
 }
 
 export function getSecretsChecksum() {
@@ -39,8 +42,8 @@ export function secretsSyncMode(env = process.env) {
  * anything. The node's store is never replaced wholesale and the node keeps
  * its own master password.
  */
-export async function syncGrantedSecrets(leaderIp, { dir = brainDir, fetchImpl = fetch } = {}) {
-  const base = meshUrl(leaderIp, '/api/secrets/mesh');
+export async function syncGrantedSecrets(leaderIp, { dir = brainDir, fetchImpl = fetch, port } = {}) {
+  const base = meshUrl(leaderIp, '/api/secrets/mesh', port);
   const listResponse = await fetchImpl(base, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
   if (!listResponse.ok) throw new Error(`Leader returned ${listResponse.status}`);
   const { keys } = await listResponse.json();
@@ -76,6 +79,6 @@ export async function syncLoop() {
   if (await isLeader()) return;
   const leaderInfo = await getLeaderInfo();
   if (!leaderInfo?.ip) return;
-  try { await syncGrantedSecrets(leaderInfo.ip); }
-  catch (err) { logger.error('secrets-sync', 'Failed to sync granted secrets', { error: err.message }); }
+  try { await syncGrantedSecrets(leaderInfo.ip, { port: leaderInfo.brain_port }); }
+  catch (err) { logger.error('secrets-sync', 'Failed to sync granted secrets', { error: err.message, leader: leaderInfo.ip, port: leaderInfo.brain_port ?? 'default' }); }
 }

package/scaffold/.agent/skills/total-recall/plugins/mesh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-mesh",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Headscale and Tailscale SSH control-server mesh administration and node discovery",
   "scripts": {

package/scaffold/.agent/skills/total-recall/plugins/mesh/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "mesh",
   "name": "Headscale",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Control-server mesh administration, Tailscale SSH, and peer node discovery.",
   "license": "MIT",
   "branding": {

package/scaffold/.agent/skills/total-recall/plugins/mesh/src/core/leader-election.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { getMeshPeers, getMeshSelf } from './mesh.mjs';
+import { getMeshPeers, getMeshSelf, listEnrichedMeshNodes } from './mesh.mjs';
 import { brainDir } from './config.mjs';
 
 /**
@@ -26,12 +26,12 @@ export const FAILOVER_BOUND_MS = 12_000;
  * Operator pin for which node leads.
  *
  * Lowest-online-IP is deterministic, but it says nothing about whether that node
- * can actually run the daemon. On this mesh the shared droplet holds the lowest
- * IP (100.64.0.1) and runs no Total Recall at all — it captured leadership
- * permanently, so it could never serve `/api/secrets/sync` and every other node
- * idled as a follower: no research, no dream cycle, no surface recompile,
- * anywhere. Followers skip the task loop entirely, so "lowest IP" quietly became
- * "nobody works".
+ * can actually run the daemon. A shared or infrastructure node can hold the
+ * lowest address while running no Total Recall at all, so it captures
+ * leadership permanently and can never serve `/api/secrets/sync`; every other
+ * node idles as a follower: no research, no dream cycle, no surface recompile,
+ * anywhere. Followers skip the task loop entirely, so "lowest IP" quietly
+ * became "nobody works".
  *
  * Set `TR_LEADER_IP` to the mesh IP of the machine that owns the canonical brain
  * on EVERY node that runs Total Recall, so they all agree on the answer. A node
@@ -70,18 +70,27 @@ function compareNodes(a, b) {
  * each node wrote a private, node-local lease document and could elect itself.
  */
 export async function getLeaderInfo() {
-  const nodes = getMeshPeers({ includeSelf: true }).filter((node) => node.online);
+  // Use the ENTITY-ENRICHED node list, not getMeshPeers(). `brain_port` is an
+  // entity variable: it lives in the vault's mesh-node document and is absent
+  // from raw Tailscale status. getMeshPeers() reads only that status, so its
+  // `brain_port` was always null and every caller fell back to port 3000 --
+  // while the leader was reachable the whole time on its real port.
+  const nodes = listEnrichedMeshNodes().filter((node) => node.online);
   if (nodes.length === 0) return null;
 
   const pin = leaderPin();
   if (pin) {
     const pinned = nodes.find((node) => node.ip === pin);
     if (!pinned) return null;
-    return { hostname: pinned.hostname, ip: pinned.ip, strategy: 'pinned-mesh-ip' };
+    return { hostname: pinned.hostname, ip: pinned.ip, brain_port: pinned.brain_port ?? null, strategy: 'pinned-mesh-ip' };
   }
 
   const leader = [...nodes].sort(compareNodes)[0];
-  return { hostname: leader.hostname, ip: leader.ip, strategy: 'lowest-mesh-ip' };
+  // `brain_port` is carried through because the leader does not necessarily
+  // serve on the default port. It was dropped here, so callers such as
+  // secrets-sync fell back to 3000 and reported "fetch failed" against a leader
+  // that was up and reachable the whole time on a different port.
+  return { hostname: leader.hostname, ip: leader.ip, brain_port: leader.brain_port ?? null, strategy: 'lowest-mesh-ip' };
 }
 
 /**

package/src/cli/agent-dir.mjs

@@ -12,6 +12,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { detectProjectBrain as detectProjectBrainInConfig } from '../core/config.mjs';
 
 /**
  * Parse --global / --project layer flags from CLI args.
@@ -39,32 +40,18 @@ export function getGlobalBrainDir() {
 }
 
 /**
- * Detect a project-level brain by checking <cwd>/.agent/skills/total-recall/.
- * Returns { agentDir, brainDir } or null.
+ * Detect a project-level brain by checking `<dir>/.agent/skills/total-recall/`
+ * (and the `.agents` spelling). Returns `{ agentDir, brainDir, projectRoot }`.
+ *
+ * Delegates to core/config.mjs so there is exactly ONE implementation of the
+ * rule. These were two independent copies that had already diverged: one
+ * checked `.agent` only, ignored `AGENT_DIR`, and required `SKILL.md`, so they
+ * could disagree about whether a project brain exists at all — and their
+ * callers then disagreed about where the surface belongs.
  */
 export function detectProjectBrain(startDir = process.cwd()) {
   if (process.env._TR_TEST_AGENT_DIR) return null;
-  let dir = startDir;
-  const homeDir = os.homedir();
-  while (dir !== path.dirname(dir)) {
-    if (dir === homeDir) break; // don't detect global as project
-    const candidates = [
-      { dir: path.join(dir, '.agent'), candidate: path.join(dir, '.agent', 'skills', 'total-recall') },
-      { dir: path.join(dir, '.agents'), candidate: path.join(dir, '.agents', 'skills', 'total-recall') }
-    ];
-    for (const c of candidates) {
-      if (fs.existsSync(path.join(c.candidate, 'SKILL.md')) || fs.existsSync(path.join(c.candidate, 'memory-vault'))) {
-        return {
-          agentDir: c.dir,
-          // Project brain lives at the detected candidate — never alias to global.
-          brainDir: c.candidate,
-          projectRoot: dir,
-        };
-      }
-    }
-    dir = path.dirname(dir);
-  }
-  return null;
+  return detectProjectBrainInConfig(startDir);
 }
 
 /**
@@ -122,6 +109,37 @@ export function getBothBrains(targetPath = process.cwd()) {
   };
 }
 
+/**
+ * The directory an instruction surface belongs in, which is NOT always the
+ * agent dir. Harnesses read `AGENTS.md`/`CLAUDE.md` at the workspace root:
+ *   global  -> <home>/.agent      (the agent dir IS the workspace root)
+ *   project -> <projectRoot>      (the repo root, NOT <repo>/.agent)
+ *
+ * Writing a project surface into `<repo>/.agent/` puts it where no harness
+ * looks, while the compile still reports success and "0 drift". Every caller
+ * that writes INSTRUCTIONS.md or client shims must use this instead of
+ * `resolveAgentDir`, which names the brain's own directory.
+ */
+export function resolveSurfaceDir(layer = 'auto', targetPath = process.cwd()) {
+  if (process.env.AGENT_DIR || process.env._TR_TEST_AGENT_DIR) {
+    return process.env.AGENT_DIR || process.env._TR_TEST_AGENT_DIR;
+  }
+  if (layer === 'global') return getGlobalAgentDir();
+  const project = detectProjectBrain(targetPath);
+  if (!project) {
+    if (layer === 'project') throw new Error('No project brain found. Run `npx total-recall init --project` to create one.');
+    return getGlobalAgentDir();
+  }
+  return project.projectRoot || project.agentDir;
+}
+
+/**
+ * The path of the canonical instruction surface for a layer.
+ */
+export function resolveInstructionsFile(layer = 'auto', targetPath = process.cwd()) {
+  return path.join(resolveSurfaceDir(layer, targetPath), 'INSTRUCTIONS.md');
+}
+
 /**
  * Determine the default layer for a memory category.
  * Always defaults to project brain. Use --global to explicitly target global.

package/src/cli/config.mjs

@@ -25,6 +25,11 @@ const KEY_MAP = {
   'rules_invariants_budget_chars': { file: 'surface', path: 'rules.invariants_budget_chars', type: 'number' },
   'rules_preferences_budget_chars': { file: 'surface', path: 'rules.preferences_budget_chars', type: 'number' },
   'rules_corrections_budget_chars': { file: 'surface', path: 'rules.corrections_budget_chars', type: 'number' },
+
+  // Token budget for the `context` instruction capsule. Raise it above the
+  // default when every rule should load for every action instead of being
+  // narrowed by applicability.
+  'context_budget': { file: 'surface', path: 'context.budget', type: 'number' },
 };
 
 function resolveKeyInfo(key) {
@@ -113,6 +118,23 @@ function castAndValidate(valueStr, type, allowedValues) {
   return valueStr;
 }
 
+export function readConfigValue(key, layer = 'global') {
+  const info = KEY_MAP[key];
+  if (!info) throw new Error(`Unknown config key: ${key}`);
+  const configDir = path.join(resolveBrainDir(layer), 'config');
+  const filePath = path.join(configDir, `${info.file}.yml`);
+  if (!fs.existsSync(filePath)) return undefined;
+  let parsed = {};
+  try { parsed = yaml.parse(fs.readFileSync(filePath, 'utf8')) || {}; } catch { return undefined; }
+  const parts = info.path.split('.');
+  let current = parsed;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
 export default async function configCommand(args) {
   const { layer, remainingArgs } = parseLayerFlag(args);
   const command = remainingArgs[0] || 'get';
@@ -140,6 +162,7 @@ export default async function configCommand(args) {
     rules_invariants_budget_chars    Characters for the invariants section of CLAUDE.md/AGENTS.md (number; default 9000)
     rules_preferences_budget_chars   Same for preferences (default 4000)
     rules_corrections_budget_chars   Same for corrections (default 8000)
+    context_budget               Token budget for the context instruction capsule (number; default 4000)
     allowed_origins              CORS origins (e.g. "http://localhost:5173,http://localhost:3000")
 
   Examples:

package/src/cli/connect.mjs

@@ -315,6 +315,9 @@ function bootstrapAgentDir(agentDir) {
 }
 
 function readInstructions(cwd, agentDir) {
+  // `cwd` IS the project root the caller means, so read the surface there.
+  // resolveSurfaceDir() would re-detect from process.cwd() and could name a
+  // different project than the caller is operating on.
   const candidates = [
     path.join(cwd, 'INSTRUCTIONS.md'),
     path.join(agentDir, 'INSTRUCTIONS.md')

package/src/cli/context.mjs

@@ -5,6 +5,7 @@ import { mergeGlobalRuleNodes, legacyRuleContributions } from '../core/surface.m
 import { compileContext, capsuleResponse, renderCapsule } from '../core/context-compiler.mjs';
 import { isBrainEnabled } from '../core/brain-registry.mjs';
 import { surfaceInputsHash } from '../core/command-surface.mjs';
+import { readConfigValue } from './config.mjs';
 
 export default async function context(args = []) {
   if (!args.length || args.includes('--help')) {
@@ -13,7 +14,16 @@ export default async function context(args = []) {
   }
   const { layer, remainingArgs } = parseLayerFlag(args);
   const query = remainingArgs[0];
-  let actions = [], budget = 4000, format = 'text', includeKnowledge = false, debug = false;
+  const configuredBudget = (() => {
+    for (const candidate of [layer === 'global' ? 'global' : 'project', 'global']) {
+      try {
+        const value = readConfigValue('context_budget', candidate);
+        if (Number.isFinite(value) && value > 0) return value;
+      } catch { /* fall through to the next layer */ }
+    }
+    return undefined;
+  })();
+  let actions = [], budget = configuredBudget ?? 4000, format = 'text', includeKnowledge = false, debug = false;
   for (let i = 1; i < remainingArgs.length; i++) {
     const flag = remainingArgs[i];
     if (flag === '--knowledge') { includeKnowledge = true; continue; }

package/src/cli/deploy.mjs

@@ -40,6 +40,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { resolveSurfaceDir } from './agent-dir.mjs';
 import yaml from 'yaml';
 import crypto from 'node:crypto';
 import { loadPluginModule } from '../core/plugin-runtime.mjs';
@@ -1689,7 +1690,9 @@ ${fmtLine('Target VFS:   ', '~/.agent/')}
           vaultDir: path.join(BRAIN_DIR, 'memory-vault'),
           skillsDir: path.join(AGENT_DIR, 'skills'),
           derivedDir: path.join(BRAIN_DIR, 'memory-derived'),
-          instructionsFile: path.join(AGENT_DIR, 'INSTRUCTIONS.md'),
+          // This compile reads the hardcoded global brain above, so the surface
+          // must be the global one too; auto-detect would resolve a project.
+          instructionsFile: path.join(resolveSurfaceDir('global'), 'INSTRUCTIONS.md'),
         });
         logOk('Initial compile complete');
       } catch (err) {

package/src/cli/doctor.mjs

@@ -260,6 +260,63 @@ export default async function doctor() {
     }
   }
 
+  // ── Instruction surface freshness ──
+  hr();
+  logInfo('INSTRUCTION SURFACE FRESHNESS');
+
+  // A surface that stopped being rewritten is invisible from the exit code:
+  // `compile` printed "Post-build verification passed: 0 drift" for months while
+  // the file harnesses actually read stayed frozen, because drift detection
+  // compares the vault to the jsonl indexes and never inspects the surface.
+  // This compares the surface against the vault hash it was built from.
+  try {
+    const { instructionsFilePath } = await import('../core/config.mjs');
+    const { computeVaultHash } = await import('../core/surface.mjs');
+    const { resolveBrainDir } = await import('./agent-dir.mjs');
+
+    const surfacePath = instructionsFilePath();
+    const stat = fs.statSync(surfacePath, { throwIfNoEntry: false });
+
+    // Compare against the vault that OWNS this surface. Using the global brain
+    // unconditionally compared a project surface against the global vault and
+    // warned on every run, even straight after a rebuild.
+    const brainDir = resolveBrainDir();
+    const vaultDir = path.join(brainDir, 'memory-vault');
+    const hashFile = path.join(brainDir, 'memory-derived', 'vault-hash.txt');
+    const brainExists = fs.existsSync(vaultDir);
+
+    if (!stat || !stat.isFile() || stat.size === 0) {
+      if (brainExists) {
+        // A brain exists but produced no surface: exactly the silent failure
+        // this check exists to catch, so it is a real failure.
+        logFail(`No instruction surface at ${surfacePath} — this is the file harnesses read.`);
+        failures++;
+      } else {
+        // Nothing initialised here yet; a missing surface is expected.
+        logOk(`No brain at ${brainDir} yet; no surface required.`);
+      }
+    } else {
+      logOk(`Surface present: ${surfacePath} (${stat.size} bytes)`);
+
+      if (!brainExists || !fs.existsSync(hashFile)) {
+        logWarn(`No compiled vault hash at ${hashFile}; freshness not verified.`);
+        warnings++;
+      } else {
+        const stored = fs.readFileSync(hashFile, 'utf8').trim();
+        const current = computeVaultHash(vaultDir);
+        if (stored && current && stored !== current) {
+          logWarn(`Vault ${brainDir} changed since the surface was compiled — run \`total-recall rebuild\`.`);
+          warnings++;
+        } else {
+          logOk(`Surface is current with ${brainDir}.`);
+        }
+      }
+    }
+  } catch (err) {
+    logWarn(`Surface freshness could not be determined: ${err.message}`);
+    warnings++;
+  }
+
   // ── Diagnostics Summary ──
   hr();
   console.log('\n  ┌─────────────────────────────────────────────────────────┐');

package/src/cli/dream.mjs

@@ -13,7 +13,7 @@
 
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveAgentDir, resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
+import { resolveAgentDir, resolveBrainDir, parseLayerFlag, resolveSurfaceDir } from './agent-dir.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -59,7 +59,7 @@ export default async function dream(args) {
   const skillsDir = path.join(agentDir, 'skills');
   const derivedDir = path.join(brainDir, 'memory-derived');
   const conflictsDir = path.join(brainDir, 'memory-inbox', 'conflicts');
-  const instructionsFile = path.join(agentDir, 'INSTRUCTIONS.md');
+  const instructionsFile = path.join(resolveSurfaceDir(effectiveLayer), 'INSTRUCTIONS.md');
 
   console.error('\n  🌙 Starting dream cycle...\n');
   const startTime = Date.now();

package/src/cli/forget.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains } from './agent-dir.mjs';
+import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains, resolveSurfaceDir } from './agent-dir.mjs';
 import { compileSurface } from '../core/surface.mjs';
 import { isSafeVaultName } from '../core/vault.mjs';
 import { getNodes } from '../core/vault-cache.mjs';
@@ -65,8 +65,10 @@ export default async function forget(args) {
     if (!remainingArgs.includes('--no-compile')) {
       const brainDir = path.dirname(globalVaultDir);
       const agentDir = path.dirname(path.dirname(brainDir));
+      // This branch operates on the GLOBAL vault, so its surface is the global
+      // one. `layer` is not in scope here and must not be invented.
       await compileSurface({ vaultDir: globalVaultDir, skillsDir: path.join(agentDir, 'skills'),
-        derivedDir: path.join(brainDir, 'memory-derived'), instructionsFile: path.join(agentDir, 'INSTRUCTIONS.md'), semantic: false });
+        derivedDir: path.join(brainDir, 'memory-derived'), instructionsFile: path.join(resolveSurfaceDir('global'), 'INSTRUCTIONS.md'), semantic: false });
     }
     return;
   }
@@ -109,7 +111,7 @@ export default async function forget(args) {
   const vaultDir = path.join(resolvedBrainDir, 'memory-vault');
   const derivedDir = path.join(resolvedBrainDir, 'memory-derived');
   const skillsDir = path.join(resolvedAgentDir, 'skills');
-  const instructionsFile = path.join(resolvedAgentDir, 'INSTRUCTIONS.md');
+  const instructionsFile = path.join(resolveSurfaceDir(layer), 'INSTRUCTIONS.md');
   const layerLabel = layer === 'project' ? '[project]' : '[global]';
 
   // Attempt deletion

package/src/cli/init.mjs

@@ -249,6 +249,9 @@ export default async function init(args) {
   if (!fs.existsSync(path.join(authSource, 'plugin.json'))) throw new Error('Required auth scaffold is missing');
   if (!fs.existsSync(authTarget) && !opts.dryRun) fs.cpSync(authSource, authTarget, { recursive: true, errorOnExist: true, force: false });
 
+  // Every scaffold plugin's node_modules are wired in Step 2.5, after the skill
+  // tree has been copied into the brain (see the note there).
+
   // ── Step 2: Seed core skills ──
   logStep('2/4', 'Installing core skills into .agent/skills/');
 
@@ -304,9 +307,19 @@ export default async function init(args) {
   }
 
   // ── Step 2.5: Create data directories inside the meta-skill (brain dir) ──
+  // Wire every scaffold plugin's dependencies AFTER the skill copy above: the
+  // plugin directories only exist once the skill tree has been copied, so an
+  // earlier pass silently skipped everything except auth (copied separately).
+  // A plugin shipped without its node_modules aborts plugin loading for the whole
+  // scope — the symptom was 'Cannot find package express' on an unrelated command.
   if (!opts.dryRun) {
     const { preparePluginDependencies } = await import('../core/plugin-dependencies.mjs');
-    preparePluginDependencies(path.join(brainDir, 'plugins', 'auth'));
+    const installedPluginsDir = path.join(brainDir, 'plugins');
+    for (const id of (fs.existsSync(installedPluginsDir) ? fs.readdirSync(installedPluginsDir) : [])) {
+      const target = path.join(installedPluginsDir, id);
+      if (!fs.existsSync(path.join(target, 'package.json'))) continue;
+      preparePluginDependencies(target);
+    }
   }
   logStep('2.5/4', 'Creating user data directories inside meta-skill');
 

package/src/cli/memory-init.mjs

@@ -1,6 +1,7 @@
 /** Initialize portable memory without provisioning feature runtimes. */
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { getGlobalAgentDir } from './agent-dir.mjs';
 import { registerProjectBrain, writeBrainIdentity, VAULT_CATEGORIES } from '../core/memory-brain.mjs';
 
@@ -25,7 +26,12 @@ export default async function init(args = []) {
   }
   const skillFile = path.join(brainDir, 'SKILL.md');
   if (!fs.existsSync(skillFile)) {
-    fs.copyFileSync(new URL('../../templates/memory/SKILL.md', import.meta.url), skillFile);
+    // Resolve the template by PATH, not `new URL(..., import.meta.url)`. Under a
+    // transform (vitest, and any loader that does not hand back a file: URL)
+    // import.meta.url is not a file URL and the copy throws
+    // "The URL must be of scheme file", which aborted the whole init.
+    const template = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates', 'memory', 'SKILL.md');
+    fs.copyFileSync(template, skillFile);
   }
   const existingIdentity = fs.existsSync(path.join(brainDir, 'config', 'brain.json'));
   writeBrainIdentity(brainDir, { name: existingIdentity ? undefined : project ? path.basename(process.cwd()) : 'global',
@@ -38,7 +44,10 @@ export default async function init(args = []) {
   const { compileSurface } = await import('../core/surface.mjs');
   const stats = await compileSurface({
     vaultDir: path.join(brainDir, 'memory-vault'), skillsDir: path.join(agentDir, 'skills'),
-    derivedDir: path.join(brainDir, 'memory-derived'), instructionsFile: path.join(agentDir, 'INSTRUCTIONS.md'),
+    derivedDir: path.join(brainDir, 'memory-derived'),
+    // This function knows the layer as a boolean, not a `layer` variable, and
+    // already passes projectRoot below. Use the same source of truth.
+    instructionsFile: path.join(project ? process.cwd() : agentDir, 'INSTRUCTIONS.md'),
     projectRoot: project ? process.cwd() : path.dirname(agentDir), semantic: false,
   });
   console.log(`Initialized ${project ? 'project' : 'global'} memory: ${brainDir} (${stats.nodesProcessed} nodes)`);

package/src/cli/plugin/create.mjs

@@ -300,6 +300,22 @@ export async function run(argv = []) {
   const args = Array.isArray(argv) ? argv.slice(3) : [];
   const sub = args[0] || "status";
   const json = args.includes("--json");
+  const wantsHelp = args.includes("--help") || args.includes("-h");
+
+  if (wantsHelp || sub === "help") {
+    const subs = ["status", ...Object.keys(IMPLEMENTED)];
+    console.log(\`${pluginName} v${manifest.version}
+
+Usage: total-recall ${id} <subcommand> [options]
+
+Subcommands:
+\${subs.map((s) => \`  \${s}\`).join("\\n")}
+
+Options:
+  --json      Machine-readable output
+  --help, -h  Show this help\`);
+    return;
+  }
 
   if (sub === "status") {
     const status = { plugin: ${JSON.stringify(id)}, implemented: Object.keys(IMPLEMENTED) };
@@ -312,7 +328,7 @@ export async function run(argv = []) {
 
   if (IMPLEMENTED[sub]) return IMPLEMENTED[sub](args.slice(1));
 
-  console.error(\`${pluginName}: "\${sub}" is not implemented.\`);
+  console.error(\`${pluginName}: "\${sub}" is not implemented. Run 'total-recall ${id} --help' for available subcommands.\`);
   process.exitCode = 2;
 }
 export default run;
@@ -494,7 +510,7 @@ const manifest = JSON.parse(fs.readFileSync(path.join(root, 'plugin.json'), 'utf
 
 test('manifest identifies the plugin', () => {
   assert.equal(manifest.id, ${JSON.stringify(id)});
-  assert.match(manifest.version, /^\\\\d+\\\\.\\\\d+\\\\.\\\\d+/);
+  assert.match(manifest.version, /^\\d+\\.\\d+\\.\\d+/);
   assert.equal(manifest.license, 'MIT');
 });
 

package/src/cli/plugin/install.mjs

@@ -33,7 +33,17 @@ export async function installPlugin(args = []) {
       return;
     }
     const { autoCompileSurfaces } = await import('../../core/auto-compile.mjs');
-    if (!await autoCompileSurfaces({ layer: isGlobal ? 'global' : 'project', semantic: false, force: true })) process.exitCode = 1;
+    // Compile the layer the plugin actually landed in. `scope` is not enough on
+    // its own: from a directory with no project brain, projectPluginsDir(cwd)
+    // resolves to the global plugins dir, so a plugin installed into the global
+    // brain still reports scope 'project'. Ask the resolver whether a project
+    // brain exists at all, and otherwise fall back to the global layer — the one
+    // that was really written. Assuming 'project' compiled nothing and printed
+    // "Auto-compile failed: No project brain found" after a successful install.
+    const { resolveBrainDir } = await import('../agent-dir.mjs');
+    let targetLayer = 'global';
+    try { resolveBrainDir('project'); targetLayer = 'project'; } catch { targetLayer = 'global'; }
+    if (!await autoCompileSurfaces({ layer: targetLayer, semantic: false, force: true })) process.exitCode = 1;
   } catch (err) {
     console.error(`❌ ${err.message}`);
     process.exit(1);