total-recall-brain 3.9.0 → 3.10.0

package/src/cli/skill-projection.mjs

@@ -0,0 +1,214 @@
+/**
+ * Scope-aware skill → slash-command projection.
+ *
+ * A "repo skill" is any <skills-root>/<name>/SKILL.md directory (the Agent
+ * Skills standard). Each IDE turns such a directory into a /<name> slash
+ * command, but every IDE looks in a *different* place, and the right place
+ * depends on the *scope* of the skill:
+ *
+ *   PROJECT skills (authored in <repo>/.agent/skills or <repo>/.agents/skills)
+ *     → project into the *repo's* IDE skill dirs, and only for IDEs actually
+ *       in use in this repo (project marker dir present, or current process is
+ *       that IDE). They belong to this repo, not the whole machine.
+ *
+ *   GLOBAL skills (authored in ~/.agent/skills)
+ *     → project into each IDE's *global* skill dir, for IDEs installed on this
+ *       machine. They are available in every repo.
+ *
+ * This mirrors the brain model: `init --project` ⇒ project skills; `init`
+ * (global) ⇒ global skills. Codex has no project-local skills dir (it only
+ * reads ~/.codex/skills globally), so it participates in GLOBAL projection only;
+ * pushing project skills to Codex is opt-in via `connect codex`.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * IDE skill descriptors. Each IDE declares how it is detected and where its
+ * skills live, per scope:
+ *   project: { dir, markers, env }  — repo-relative dest; detected by repo
+ *            marker dirs or current-process env vars. null ⇒ no project skills.
+ *   global:  { dir, markers }       — home-relative dest; detected by home
+ *            marker dirs (i.e. the IDE is installed). null ⇒ no global skills.
+ */
+export const IDE_SKILLS = [
+  {
+    id: 'claude-code',
+    label: 'Claude Code',
+    clients: ['claude-code'],
+    project: { dir: ['.claude', 'skills'], markers: ['.claude'], env: ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT'] },
+    global:  { dir: ['.claude', 'skills'], markers: ['.claude'] }
+  },
+  {
+    id: 'agents',
+    label: 'Antigravity / Gemini',
+    clients: ['antigravity', 'gemini'],
+    // Antigravity & Gemini both read <repo>/.agents/skills as the workspace
+    // Agent-Skills location. Their *global* surface is ~/.gemini/commands
+    // (markdown commands), wired by the slash-command writer, not here.
+    project: { dir: ['.agents', 'skills'], markers: ['.agents', '.gemini'], env: ['ANTIGRAVITY', 'GEMINI_CLI'] },
+    global:  null
+  },
+  {
+    id: 'codex',
+    label: 'Codex',
+    clients: ['codex'],
+    // Codex only discovers skills globally under ~/.codex/skills. There is no
+    // project-local dir, so project skills are opt-in (namespaced) via connect.
+    project: null,
+    global:  { dir: ['.codex', 'skills'], markers: ['.codex'] }
+  }
+];
+
+function pathExists(filePath) {
+  try {
+    fs.lstatSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Skill source roots, in priority order. The canonical Total Recall location
+ * (.agent/skills, singular) wins, but we also scan the Antigravity-native
+ * .agents/skills (plural) so a skill authored in either place is discovered.
+ */
+export function skillSourceRoots(agentDir) {
+  const roots = [path.join(agentDir, 'skills')];
+  const parent = path.dirname(agentDir);
+  if (path.basename(agentDir) === '.agent') {
+    roots.push(path.join(parent, '.agents', 'skills'));
+  }
+  return roots;
+}
+
+/**
+ * Discover repo skills to expose as slash commands.
+ * Every <root>/<name>/ directory containing a SKILL.md is a skill. When the
+ * same name appears in more than one source root, the canonical root wins.
+ */
+export function discoverRepoSkills(agentDir) {
+  const seen = new Map();
+  for (const skillsRoot of skillSourceRoots(agentDir)) {
+    if (!fs.existsSync(skillsRoot)) continue;
+    let entries;
+    try {
+      entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+      if (seen.has(entry.name)) continue;
+      const skillDir = path.join(skillsRoot, entry.name);
+      if (!fs.existsSync(path.join(skillDir, 'SKILL.md'))) continue;
+      seen.set(entry.name, { name: entry.name, skillDir });
+    }
+  }
+  return [...seen.values()];
+}
+
+/**
+ * Symlink each discovered skill dir into one IDE's Agent-Skills directory.
+ * Idempotent, self-healing, and strictly additive: a symlink that is broken or
+ * stale is refreshed even without --force; a *real* (non-symlink) entry is
+ * never clobbered unless --force (so a user's own skill always wins a name
+ * collision); a skill whose source already *is* the destination is left alone.
+ */
+export function projectSkillsAsCommands(destDir, skills, opts = {}) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const written = [];
+  for (const skill of skills) {
+    const linkPath = path.join(destDir, skill.name);
+    const wantTarget = path.resolve(skill.skillDir);
+
+    if (path.resolve(linkPath) === wantTarget) {
+      written.push({ name: skill.name, action: 'source' });
+      continue;
+    }
+
+    if (pathExists(linkPath)) {
+      const stat = fs.lstatSync(linkPath);
+      if (stat.isSymbolicLink()) {
+        const current = path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath));
+        if (current === wantTarget && fs.existsSync(linkPath) && !opts.force) {
+          written.push({ name: skill.name, action: 'exists' });
+          continue;
+        }
+        fs.unlinkSync(linkPath); // stale, broken, or --force → refresh
+      } else if (!opts.force) {
+        written.push({ name: skill.name, action: 'skipped' }); // user's real file/dir wins
+        continue;
+      } else {
+        fs.rmSync(linkPath, { recursive: true, force: true });
+      }
+    }
+    fs.symlinkSync(skill.skillDir, linkPath);
+    written.push({ name: skill.name, action: 'linked' });
+  }
+  return written;
+}
+
+/**
+ * Is an IDE target active for the given scope?
+ *   project → repo has a marker dir, or the current process is this IDE (env)
+ *   global  → the IDE is installed (home marker dir present)
+ */
+function isTargetActive(target, scope, cwd, env) {
+  const spec = target[scope];
+  if (!spec) return false;
+  if (scope === 'project') {
+    if ((spec.markers || []).some(m => pathExists(path.join(cwd, m)))) return true;
+    if ((spec.env || []).some(v => env[v] != null && env[v] !== '')) return true;
+    return false;
+  }
+  // global
+  return (spec.markers || []).some(m => pathExists(path.join(os.homedir(), m)));
+}
+
+/**
+ * Resolve which IDE targets are active (and where they project to) for a scope.
+ * Returns every target annotated with { active, destDir } so callers can both
+ * wire the active ones and advertise the inactive ones as opt-in.
+ */
+export function detectActiveSkillTargets({ scope, cwd = process.cwd(), env = process.env }) {
+  return IDE_SKILLS.map(target => {
+    const spec = target[scope];
+    const active = isTargetActive(target, scope, cwd, env);
+    let destDir = null;
+    if (spec) {
+      destDir = scope === 'global'
+        ? path.join(os.homedir(), ...spec.dir)
+        : path.join(cwd, ...spec.dir);
+    }
+    return { id: target.id, label: target.label, clients: target.clients, scope, supported: !!spec, active, destDir };
+  });
+}
+
+/**
+ * Project discovered skills into every *active* IDE skill dir for one scope.
+ * Used by `init`: project skills on `init --project`, global skills on `init`.
+ *
+ * @returns {{ scope, skills, wired: Array, available: Array }}
+ *   wired     — targets we projected into (active + supported)
+ *   available — supported-but-inactive targets, surfaced as opt-in `connect`
+ */
+export function projectSkillsForScope({ scope, cwd = process.cwd(), agentDir, opts = {}, env = process.env }) {
+  const skills = discoverRepoSkills(agentDir);
+  const targets = detectActiveSkillTargets({ scope, cwd, env });
+  const wired = [];
+  const available = [];
+
+  for (const target of targets) {
+    if (!target.supported) continue;
+    if (target.active && skills.length > 0) {
+      const results = projectSkillsAsCommands(target.destDir, skills, opts);
+      wired.push({ ...target, results });
+    } else if (!target.active) {
+      available.push(target);
+    }
+  }
+  return { scope, skills, wired, available };
+}

package/src/cli/skill.mjs

@@ -1,16 +1,30 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { resolveAgentDir, parseLayerFlag } from './agent-dir.mjs';
 
 // Helper to resolve agent directories dynamically
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '../../');
-const agentDir = path.join(ROOT, '.agent');
-const skillsDir = path.join(agentDir, 'skills');
 
-// Direct dynamic imports for scripts layer to preserve environment paths
-const scriptsPath = path.join(agentDir, 'skills', 'total-recall', 'skills', 'skill', 'scripts');
+export function resolveSkillScriptPath(scriptName, { agentDir = resolveAgentDir(), root = ROOT } = {}) {
+  const candidates = [
+    path.join(agentDir, 'skills', 'total-recall', 'skills', 'tr-skill', 'scripts', scriptName),
+    path.join(agentDir, 'skills', 'total-recall', 'skills', 'skill', 'scripts', scriptName),
+    path.join(root, 'scaffold', '.agent', 'skills', 'total-recall', 'skills', 'tr-skill', 'scripts', scriptName),
+    path.join(root, 'scaffold', '.agent', 'skills', 'total-recall', 'skills', 'skill', 'scripts', scriptName),
+  ];
+  const found = candidates.find(candidate => fs.existsSync(candidate));
+  if (!found) {
+    throw new Error(`Could not find bundled skill helper "${scriptName}". Checked: ${candidates.join(', ')}`);
+  }
+  return found;
+}
+
+async function importSkillScript(scriptName, options) {
+  return import(pathToFileURL(resolveSkillScriptPath(scriptName, options)).href);
+}
 
 function printHelp() {
   console.log(`
@@ -28,6 +42,8 @@ function printHelp() {
     remove <name>         Safely delete a skill package and hot-recompile shims (alias: rm)
 
   Options:
+    --global              Target the global brain (~/.agent)
+    --project             Target the current repo's project brain
     --help, -h            Show this help menu
   
   Examples:
@@ -40,15 +56,24 @@ function printHelp() {
 }
 
 export default async function skillCli(args) {
-  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  if (remainingArgs.length === 0 || remainingArgs.includes('--help') || remainingArgs.includes('-h')) {
     printHelp();
     return;
   }
 
-  const command = args[0];
+  let agentDir;
+  try {
+    agentDir = resolveAgentDir(layer);
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+  const skillsDir = path.join(agentDir, 'skills');
+  const command = remainingArgs[0];
 
   if (command === 'find') {
-    const query = args[1];
+    const query = remainingArgs[1];
     if (!query) {
       console.error('❌ You must provide a search query.');
       console.error('Usage: npx total-recall skill find <query>');
@@ -56,7 +81,7 @@ export default async function skillCli(args) {
     }
 
     try {
-      const { searchAndSort } = await import('../../.agent/skills/total-recall/skills/skill/scripts/find-skills.mjs');
+      const { searchAndSort } = await importSkillScript('find-skills.mjs', { agentDir });
       const results = searchAndSort(query);
       
       if (results.length === 0) {
@@ -100,7 +125,7 @@ export default async function skillCli(args) {
   } 
   
   else if (command === 'install' || command === 'add' || command === 'load') {
-    const pkg = args[1];
+    const pkg = remainingArgs[1];
     if (!pkg) {
       console.error('❌ You must provide a skill package to load.');
       console.error('Usage: npx total-recall skill load <owner/repo@skill>');
@@ -108,8 +133,8 @@ export default async function skillCli(args) {
     }
 
     try {
-      const { installSkill } = await import('../../.agent/skills/total-recall/skills/skill/scripts/install-skill.mjs');
-      const res = installSkill(pkg);
+      const { installSkill } = await importSkillScript('install-skill.mjs', { agentDir });
+      const res = installSkill(pkg, { cwd: process.cwd(), agentDir });
       if (!res.success) {
         process.exit(1);
       }
@@ -120,7 +145,7 @@ export default async function skillCli(args) {
   } 
   
   else if (command === 'scan') {
-    const target = args[1];
+    const target = remainingArgs[1];
     if (!target) {
       console.error('❌ You must specify a local skill directory to scan.');
       console.error('Usage: npx total-recall skill scan <skill-name>');
@@ -130,7 +155,7 @@ export default async function skillCli(args) {
     const targetDir = path.resolve(skillsDir, target);
 
     try {
-      const { runScan } = await import('../../.agent/skills/total-recall/skills/skill/scripts/scan-skill.mjs');
+      const { runScan } = await importSkillScript('scan-skill.mjs', { agentDir });
       const result = runScan(targetDir);
       process.exit(result.success ? 0 : 1);
     } catch (err) {
@@ -176,7 +201,7 @@ export default async function skillCli(args) {
   } 
   
   else if (command === 'remove' || command === 'rm') {
-    const target = args[1];
+    const target = remainingArgs[1];
     if (!target) {
       console.error('❌ You must specify a skill name to remove.');
       console.error('Usage: npx total-recall skill remove <skill-name>');
@@ -197,7 +222,8 @@ export default async function skillCli(args) {
     console.log('🔄 Hot-recompiling active shims to reflect changes...');
     const child = spawnSync('npx', ['total-recall', 'compile'], { 
       encoding: 'utf8',
-      cwd: ROOT
+      cwd: process.cwd(),
+      env: { ...process.env, AGENT_DIR: agentDir },
     });
 
     if (child.error || child.status !== 0) {
@@ -208,7 +234,7 @@ export default async function skillCli(args) {
   } 
   
   else if (command === 'create' || command === 'new') {
-    const target = args[1];
+    const target = remainingArgs[1];
     if (!target) {
       console.error('❌ You must specify a skill name to create.');
       console.error('Usage: npx total-recall skill create <skill-name>');
@@ -285,7 +311,7 @@ Provide a high-level explanation of the skill's capabilities and context.
   }
 
   else if (command === 'edit') {
-    const target = args[1];
+    const target = remainingArgs[1];
     if (!target) {
       console.error('❌ You must specify a skill name to edit.');
       console.error('Usage: npx total-recall skill edit <skill-name>');

package/src/core/daemon-loop.mjs

@@ -293,6 +293,14 @@ process.on('SIGINT', () => {
   running = false;
 });
 
+process.on('uncaughtException', (err) => {
+  logger.error({ subsystem: 'daemon-loop', message: `Uncaught Exception (suppressed to keep daemon alive): ${err.stack || err.message}` });
+});
+
+process.on('unhandledRejection', (reason, promise) => {
+  logger.error({ subsystem: 'daemon-loop', message: `Unhandled Rejection (suppressed to keep daemon alive): ${reason}` });
+});
+
 async function main() {
   logger.info({
     subsystem: 'daemon-loop',
@@ -416,8 +424,11 @@ async function main() {
           // If the task was skipped because it requires an LLM, DO NOT complete the research project.
           if (result.skippedLLM) {
             patch.status = 'pending';
-          } else if (result.success && result.factSlug) {
-            if (task._research_phase === 'acquisition') {
+          } else if (result.success) {
+            if (task._research_phase === 'acquisition' && !result.factSlug) {
+              patch.status = 'failed';
+              patch.notes = 'No insights found during acquisition.';
+            } else if (task._research_phase === 'acquisition') {
               patch.status = 'pending';
               patch.research_phase = 'deliberation';
               patch.completed_at = new Date().toISOString();

package/src/core/operation-validator.mjs

@@ -7,6 +7,7 @@ import {
   OperationEnvelopeSchema,
   PatchEnvelopeSchema,
   EventEnvelopeSchema,
+  DeleteEnvelopeSchema,
 } from './schema.mjs';
 import { atomicWrite, safeStringify } from './vault.mjs';
 import { logger } from './logger.mjs';
@@ -109,7 +110,7 @@ export function processOperation(envelope, vaultRoot, options = {}) {
   const warnings = [];
 
   // Stage 1: Envelope Validation
-  const schemaMap = { operation: OperationEnvelopeSchema, patch: PatchEnvelopeSchema, event: EventEnvelopeSchema };
+  const schemaMap = { operation: OperationEnvelopeSchema, patch: PatchEnvelopeSchema, event: EventEnvelopeSchema, delete: DeleteEnvelopeSchema };
   const envSchema = schemaMap[envelope.type];
   if (!envSchema) return makeErrorResponse(envelope.type || 'unknown', operationId, envelope.path || '', [`Unknown envelope type: ${envelope.type}`]);
   const envResult = envSchema.safeParse(envelope);
@@ -189,6 +190,17 @@ export function processOperation(envelope, vaultRoot, options = {}) {
   }
   if (envelope.type === 'event') { try { JSON.parse(envelope.content); } catch { errors.push('Event content must be valid JSON.'); } }
 
+  if (envelope.type === 'delete') {
+    const absPath = resolveVfsPath(vaultRoot, envelope.path);
+    if (!fs.existsSync(absPath)) { errors.push(`Target file does not exist for delete: ${envelope.path}`); }
+    else {
+      const { data } = matter(fs.readFileSync(absPath, 'utf8'));
+      resolvedType = data.type || null;
+      // §6.2: append-type documents are immutable and may not be deleted.
+      if (APPEND_TYPES.has(resolvedType)) errors.push(`Append-type '${resolvedType}' may not be deleted.`);
+    }
+  }
+
   const isValid = errors.length === 0;
   if (envelope.dry_run || !isValid) {
     const resp = { success: isValid, type: envelope.type, operation_id: operationId, path: envelope.path, committed_at: null, dry_run: !!envelope.dry_run, validation: { valid: isValid, type: resolvedType, errors, warnings } };
@@ -230,6 +242,12 @@ export function processOperation(envelope, vaultRoot, options = {}) {
       const logDir = eventLogDir || path.join(vaultRoot, '.events');
       if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
       fs.appendFileSync(path.join(logDir, `${envelope.workspace_id}.jsonl`), JSON.stringify({ event_id: operationId, event_type: 'operation-audit', ts: committedAt, path: envelope.path, content: envelope.content, idempotency_key: envelope.idempotency_key }) + '\n');
+    } else if (envelope.type === 'delete') {
+      fs.rmSync(absPath, { force: true });
+      // §6.2: a delete emits an auditable deletion event so history is never lost.
+      const logDir = eventLogDir || path.join(vaultRoot, '.events');
+      if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+      fs.appendFileSync(path.join(logDir, `${envelope.workspace_id}.jsonl`), JSON.stringify({ event_id: operationId, event_type: 'delete', ts: committedAt, path: envelope.path, resolved_type: resolvedType, idempotency_key: envelope.idempotency_key }) + '\n');
     }
   } catch (err) {
     logger.error('operation-validator', `Commit failed: ${err.message}`);

package/src/core/research.mjs

@@ -109,11 +109,25 @@ async function planResearchQueries(task, context) {
   const today = getLocalizedDateTime();
   const cutoff = context.runtimeConfig?.training_cutoff || 'January 2025';
 
-  const planSystem = `You are a Research Planner. Today's date and time is ${today}. The model's training data cutoff is ${cutoff}.
-Decompose the research objective into 3 distinct, specific search queries. Prioritize queries targeting fresh, timely information that has arisen or been updated since the training cutoff.
-Output ONLY valid JSON: { "queries": ["query 1", "query 2", "query 3"], "source_hints": { "query 1": ["brave-search", "arxiv"] } }`;
-
-  const planPrompt = `Research Objective: ${task.target}\nDetails: ${task.body || ''}\nGenerate 3 targeted search queries targeting active, timely information post-${cutoff}.`;
+  const planSystem = `<system_instructions>
+You are a Research Planner.
+- Decompose the research objective into 3 distinct, specific search queries.
+- Prioritize queries targeting fresh, timely information that has arisen or been updated since the training cutoff.
+- ALWAYS think inside a <scratchpad> block first to outline your queries.
+- Your final output MUST be ONLY valid JSON matching this schema: { "queries": ["query 1", "query 2", "query 3"], "source_hints": { "query 1": ["brave-search", "arxiv"] } }
+</system_instructions>
+
+<context>
+Today's date and time is ${today}.
+The model's training data cutoff is ${cutoff}.
+</context>`;
+
+  const planPrompt = `<user_goal>
+Research Objective: ${task.target}
+Details: ${task.body || 'None'}
+</user_goal>
+
+Generate 3 targeted search queries targeting active, timely information post-${cutoff}.`;
 
   try {
     const raw = await callLocalRuntime(planPrompt, planSystem, context.runtimeConfig);
@@ -436,12 +450,36 @@ async function synthesizeLocally(task, results, runtimeConfig) {
     .map(r => `[${r.source}] ${r.title}: ${r.snippet?.slice(0, 300)}`)
     .join('\n');
 
-  const system = `You are a Deep Research Synthesizer. Today's date and time is ${today}. The model's training data cutoff is ${cutoff}.
-Synthesize research results into a concise report. Cite sources inline [Source: URL]. Prioritize fresh, timely information published after the cutoff.`;
-  const prompt = `Topic: "${task.target}"\n\nResults:\n${sourceSummary.slice(0, 6000)}`;
+  const system = `<system_instructions>
+You are a Deep Research Synthesizer.
+- Synthesize research results into a concise report.
+- Cite sources inline [Source: URL].
+- Prioritize fresh, timely information published after the cutoff.
+- ALWAYS use a <scratchpad> block first to outline your synthesis and evaluate source reliability before writing the final report.
+</system_instructions>
+
+<context>
+Today's date and time is ${today}.
+The model's training data cutoff is ${cutoff}.
+</context>`;
+
+  const prompt = `<user_goal>
+Topic: "${task.target}"
+</user_goal>
+
+<retrieved_docs>
+${sourceSummary.slice(0, 6000)}
+</retrieved_docs>
+
+Please synthesize the research results.`;
 
   try {
-    return callLocalRuntime(prompt, system, runtimeConfig);
+    let report = await callLocalRuntime(prompt, system, runtimeConfig);
+    // Remove the scratchpad from the final stored report
+    if (report) {
+      report = report.replace(/<scratchpad>[\s\S]*?<\/scratchpad>/gi, '').trim();
+    }
+    return report;
   } catch (err) {
     logger.error('research: callLocalRuntime failed during synthesis', { err: err.message });
     return null;

package/src/core/runtime.mjs

@@ -35,8 +35,8 @@ export function findBinaryInPath(binaryName) {
  * Total Recall Runtime — CLI Agent Dispatch
  *
  * All reasoning tasks are dispatched to headless CLI agents.
- * Agent registry lives in the cli-agents skill:
- *   .agent/skills/total-recall/skills/cli-agents/agents.yml
+ * Agent registry lives in the tr-cli-agents skill:
+ *   .agent/skills/total-recall/skills/tr-cli-agents/agents.yml
  */
 
 // ─── Default agent registry (used when agents.yml doesn't exist) ─────────────
@@ -51,11 +51,18 @@ const DEFAULT_AGENTS = [
  * Resolve the path to the cli-agents config file.
  */
 function getAgentsConfigPath() {
-  const skillPath = path.join(agentDir, 'skills', 'total-recall', 'skills', 'cli-agents', 'agents.yml');
-  if (fs.existsSync(skillPath)) return skillPath;
-  // Fallback: check if it's a standalone skill (not nested in meta-skill)
-  const standalonePath = path.join(agentDir, 'skills', 'cli-agents', 'agents.yml');
-  if (fs.existsSync(standalonePath)) return standalonePath;
+  // The cli-agents skill was namespaced to tr-cli-agents; check the new name
+  // first, then fall back to the legacy name for repos initialized before the
+  // rename, in both the nested (meta-skill) and standalone locations.
+  const candidates = [
+    path.join(agentDir, 'skills', 'total-recall', 'skills', 'tr-cli-agents', 'agents.yml'),
+    path.join(agentDir, 'skills', 'total-recall', 'skills', 'cli-agents', 'agents.yml'),
+    path.join(agentDir, 'skills', 'tr-cli-agents', 'agents.yml'),
+    path.join(agentDir, 'skills', 'cli-agents', 'agents.yml')
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
   return null;
 }
 

package/src/core/schema.mjs

@@ -284,11 +284,23 @@ export const EventEnvelopeSchema = z.object({
   intent: z.string().optional(),
 });
 
+// The canonical fourth envelope type (SSSS spec §6.2): remove a replace-type VFS
+// file. Carries no `content`; the deletion is recorded as an auditable event so
+// history is never lost. Append-type documents may not be deleted.
+export const DeleteEnvelopeSchema = z.object({
+  type: z.literal('delete'),
+  idempotency_key: z.string().min(8),
+  path: z.string(),
+  workspace_id: z.string(),
+  lease_id: z.string().optional(),
+  intent: z.string().optional(),
+});
+
 // ─── Operation Response (§6.4 of the SSSS spec) ────────────────────────────
 
 export const OperationResponseSchema = z.object({
   success: z.boolean(),
-  type: z.enum(['operation', 'patch', 'event']),
+  type: z.enum(['operation', 'patch', 'event', 'delete']),
   operation_id: z.string(),
   path: z.string(),
   committed_at: z.string().datetime().nullable(),
@@ -712,6 +724,15 @@ export const CommerceCatalogSchema = z.object({
   db_id: z.string().optional().nullable(),
 });
 
+export const EmailAccountSchema = z.object({
+  type: z.literal("email_account"),
+  email_address: z.string(),
+  display_name: z.string(),
+  provider: z.string(),
+  status: z.string(),
+  workspace_id: z.string().optional().nullable(),
+  metadata: z.record(z.unknown()).optional().nullable(),
+});
 export const ProductSchema = z.object({
   type: z.literal('product'),
   name: z.string(),
@@ -828,6 +849,7 @@ export const SSSS_SCHEMAS = {
   account_memory: AccountMemorySchema,
   account_workflow: AccountWorkflowSchema,
   workspace_transfer: WorkspaceTransferSchema,
+  email_account: EmailAccountSchema,
   extension: ExtensionSchema,
   phone_number: PhoneNumberSchema,
   domain: DomainSchema,

package/src/server/api.mjs

@@ -176,7 +176,7 @@ function resolveRequestedModel(requestedModel, runtimeConfig) {
 }
 
 function ssssReferenceDir() {
-  return path.join(SKILLS_DIR, 'total-recall', 'skills', 'ssss', 'references');
+  return path.join(SKILLS_DIR, 'total-recall', 'skills', 'tr-ssss', 'references');
 }
 
 function listSsssReferences(req) {
@@ -510,7 +510,7 @@ You have a REAL browser AND full desktop control. Use them. Navigate, click, typ
         baseSystemPrompt += `\n\n=== TIER 1 HOT MEMORY INSTRUCTIONS ===\n${compressInstructions(instructions)}`;
       }
 
-      const ssssPath = path.join(AGENT_DIR, 'skills', 'total-recall', 'skills', 'ssss', 'SKILL.md');
+      const ssssPath = path.join(AGENT_DIR, 'skills', 'total-recall', 'skills', 'tr-ssss', 'SKILL.md');
       if (fs.existsSync(ssssPath)) {
         const ssssContent = fs.readFileSync(ssssPath, 'utf8');
         baseSystemPrompt += `\n\n=== STRUCTURED SEMANTIC SYNTAX SYSTEM (SSSS) DOCUMENTATION ===\nYou are the orchestrator of this system. Here is the architectural specification:\n${compressSsssSkill(ssssContent)}`;

package/src/server/rest.mjs

@@ -1520,7 +1520,7 @@ function absoluteUrl(req, routePath) {
 }
 
 function ssssReferenceDir() {
-  return path.join(SKILLS_DIR, 'total-recall', 'skills', 'ssss', 'references');
+  return path.join(SKILLS_DIR, 'total-recall', 'skills', 'tr-ssss', 'references');
 }
 
 function listSsssReferences(req) {
@@ -1561,7 +1561,7 @@ router.get('/api/ssss', requireAuth, requireScope('ssss:read'), (req, res) => {
       name: 'ssss-skill',
       url: absoluteUrl(req, '/api/ssss/skill/ssss'),
       ...(() => {
-        const r = readTextResource(path.join(SKILLS_DIR, 'total-recall', 'skills', 'ssss', 'SKILL.md'), 'ssss-skill');
+        const r = readTextResource(path.join(SKILLS_DIR, 'total-recall', 'skills', 'tr-ssss', 'SKILL.md'), 'ssss-skill');
         return r ? { sha256: r.sha256, bytes: r.bytes, modified: r.modified } : { sha256: null, bytes: 0, modified: null };
       })()
     },
@@ -1588,7 +1588,7 @@ router.get('/api/ssss/instructions', requireAuth, requireScope('ssss:read', 'ins
 });
 
 router.get('/api/ssss/skill/ssss', requireAuth, requireScope('ssss:read'), (_req, res) => {
-  return sendTextResource(res, path.join(SKILLS_DIR, 'total-recall', 'skills', 'ssss', 'SKILL.md'), 'ssss-skill');
+  return sendTextResource(res, path.join(SKILLS_DIR, 'total-recall', 'skills', 'tr-ssss', 'SKILL.md'), 'ssss-skill');
 });
 
 router.get('/api/ssss/spec', requireAuth, requireScope('ssss:read'), (_req, res) => {