total-recall-brain 3.31.2 → 3.32.1

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/group.mjs

@@ -0,0 +1,151 @@
+/**
+ * total-recall group
+ * Manage groups of projects and groups of groups (create, add, remove, list, show, tree, members --recursive, delete).
+ * Built-in (ships with the package); was a machine-local composable command.
+ */
+export default async function (args = []) {
+  // total-recall group <create|add|remove|list|tree|members|delete|show> …
+// Groups of projects and groups of groups. Each group is an SSSS document
+// (type: project_group) in the global brain: ~/.agent/skills/total-recall/groups/<uuid>.md
+// Members are projects (random-UUID project ids) or other groups. Nesting is
+// cycle-checked; a project or group may belong to several groups.
+const fs = await import('node:fs');
+const path = await import('node:path');
+const os = await import('node:os');
+const { randomUUID } = await import('node:crypto');
+const { spawnSync } = await import('node:child_process');
+const { createRequire } = await import('node:module');
+const YAML = (await import('yaml')).default;
+
+const argl = Array.isArray(args) ? args : [];
+const asJson = argl.includes('--json');
+const recursive = argl.includes('--recursive') || argl.includes('-r');
+const pos = argl.filter((a) => !a.startsWith('-'));
+const [sub, ...rest] = pos;
+const DIR = path.join(os.homedir(), '.agent', 'skills', 'total-recall', 'groups');
+fs.mkdirSync(DIR, { recursive: true });
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const die = (m) => { process.exitCode = 1; if (asJson) console.log(JSON.stringify({ ok: false, error: m })); else console.error('✖ ' + m); };
+const help = () => console.log(`Usage: total-recall group <command> [--json]
+
+  create <name> [--description "<text>"]   New group (random UUID id)
+  add <group> <member…>                    Member = repo path (→ its project id), project UUID, or group name/UUID
+  remove <group> <member…>                 Remove members
+  list                                     All groups
+  show <group>                             One group with direct members
+  tree [<group>]                           Nested view (all roots if omitted)
+  members <group> [--recursive]            Direct members, or every project reached through nested groups
+  delete <group>                           Delete a group (refused while other groups contain it)
+
+Groups are SSSS project_group documents in ${DIR}. Nesting is cycle-checked.`);
+
+const load = () => fs.readdirSync(DIR).filter((f) => f.endsWith('.md')).map((f) => {
+  const raw = fs.readFileSync(path.join(DIR, f), 'utf8');
+  const m = raw.match(/^---\n([\s\S]*?)\n---/);
+  return m ? YAML.parse(m[1]) : null;
+}).filter(Boolean);
+const save = (g) => {
+  g.timestamp = new Date().toISOString();
+  const body = `---\n${YAML.stringify(g).trim()}\n---\n\n# ${g.title}\n\n${g.description || 'Project group.'}\n`;
+  const file = path.join(DIR, `${g.id}.md`); const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, body, { mode: 0o644 }); fs.renameSync(tmp, file);
+};
+const groups = load();
+const byId = new Map(groups.map((g) => [g.id, g]));
+const find = (ref) => groups.find((g) => g.id === ref) || groups.filter((g) => g.title === ref).at(0) || null;
+const findAll = (ref) => groups.filter((g) => g.id === ref || g.title === ref);
+const one = (ref) => { const hits = findAll(ref); if (hits.length > 1) { die(`"${ref}" matches ${hits.length} groups — use the id`); return null; } if (!hits.length) { die(`no group "${ref}"`); return null; } return hits[0]; };
+
+const projectFromPath = (p) => {
+  const abs = path.resolve(p);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return null;
+  const r = spawnSync(process.execPath, [process.argv[1], 'project-id', '--json'], { cwd: abs, encoding: 'utf8' });
+  const line = (r.stdout || '').split('\n').find((l) => l.startsWith('{"project_id"'));
+  if (r.status !== 0 || !line) return null;
+  const j = JSON.parse(line);
+  return { type: 'project', id: j.project_id, name: j.name, path: path.dirname(path.dirname(path.dirname(path.dirname(path.dirname(j.config))))) };
+};
+const resolveMember = (ref) => {
+  const g = find(ref); if (g) return { type: 'group', id: g.id, name: g.title };
+  if (UUID.test(ref)) {
+    // a bare UUID that is not a group: a project id (name/path unknown until added by path)
+    for (const x of groups) for (const m of x.members || []) if (m.type === 'project' && m.id === ref) return { ...m };
+    return { type: 'project', id: ref };
+  }
+  return projectFromPath(ref);
+};
+// does `from` (a group id) reach `target` (a group id) through nesting?
+const reaches = (from, target, seen = new Set()) => {
+  if (from === target) return true; if (seen.has(from)) return false; seen.add(from);
+  return (byId.get(from)?.members || []).some((m) => m.type === 'group' && reaches(m.id, target, seen));
+};
+const flatten = (g, seen = new Set()) => {
+  const out = new Map(); if (seen.has(g.id)) return out; seen.add(g.id);
+  for (const m of g.members || []) {
+    if (m.type === 'project') out.set(m.id, m);
+    else if (byId.has(m.id)) for (const [k, v] of flatten(byId.get(m.id), seen)) out.set(k, v);
+  }
+  return out;
+};
+const label = (m) => m.type === 'group' ? `▸ ${byId.get(m.id)?.title || m.name || m.id}  (${m.id})` : `• ${m.name || '(project)'}  ${m.id}${m.path ? '  ' + m.path : ''}`;
+const printTree = (g, depth = 0, seen = new Set()) => {
+  console.log(`${'  '.repeat(depth)}▸ ${g.title}  (${g.id})`);
+  if (seen.has(g.id)) return; seen.add(g.id);
+  for (const m of g.members || []) {
+    if (m.type === 'group' && byId.has(m.id)) printTree(byId.get(m.id), depth + 1, seen);
+    else console.log(`${'  '.repeat(depth + 1)}${label(m)}`);
+  }
+};
+
+if (!sub || sub === 'help' || argl.includes('--help') || argl.includes('-h')) { help(); return; }
+
+if (sub === 'create') {
+  const name = rest.join(' ').trim(); if (!name) return die('group create <name>');
+  const di = argl.indexOf('--description');
+  const g = { type: 'project_group', id: randomUUID(), title: name, description: di >= 0 ? argl[di + 1] : '', members: [] };
+  save(g); return asJson ? console.log(JSON.stringify({ ok: true, group: g })) : console.log(`✔ group "${name}" ${g.id}`);
+}
+if (sub === 'add' || sub === 'remove') {
+  const g = one(rest[0]); if (!g) return; const refs = rest.slice(1); if (!refs.length) return die(`group ${sub} <group> <member…>`);
+  const results = [];
+  for (const ref of refs) {
+    const m = resolveMember(ref);
+    if (!m) { results.push({ ref, ok: false, error: 'not a group, project UUID, or repo path with a project brain' }); continue; }
+    if (sub === 'add') {
+      if (m.type === 'group' && reaches(m.id, g.id)) { results.push({ ref, ok: false, error: `cycle: "${m.name}" already contains "${g.title}"` }); continue; }
+      if ((g.members || []).some((x) => x.id === m.id)) { results.push({ ref, ok: true, note: 'already a member' }); continue; }
+      g.members = [...(g.members || []), m]; results.push({ ref, ok: true, added: m });
+    } else {
+      const before = (g.members || []).length; g.members = (g.members || []).filter((x) => x.id !== m.id);
+      results.push({ ref, ok: before !== g.members.length, removed: before !== g.members.length });
+    }
+  }
+  save(g);
+  if (results.some((r) => !r.ok)) process.exitCode = 1;
+  return asJson ? console.log(JSON.stringify({ ok: !process.exitCode, group: g.id, results })) : results.forEach((r) => console.log(`${r.ok ? '✔' : '✖'} ${r.ref}${r.error ? ' — ' + r.error : r.note ? ' — ' + r.note : ''}`));
+}
+if (sub === 'list') {
+  const rows = groups.map((g) => ({ id: g.id, name: g.title, members: (g.members || []).length, projects: flatten(g).size }));
+  return asJson ? console.log(JSON.stringify(rows)) : (rows.length ? rows.forEach((r) => console.log(`▸ ${r.name}  ${r.id}  (${r.members} direct, ${r.projects} projects)`)) : console.log('No groups yet — total-recall group create <name>'));
+}
+if (sub === 'show') { const g = one(rest[0]); if (!g) return; return asJson ? console.log(JSON.stringify(g)) : (console.log(`▸ ${g.title}  ${g.id}`), (g.members || []).forEach((m) => console.log('  ' + label(m)))); }
+if (sub === 'tree') {
+  if (rest[0]) { const g = one(rest[0]); if (!g) return; return asJson ? console.log(JSON.stringify(g)) : printTree(g); }
+  const nested = new Set(groups.flatMap((g) => (g.members || []).filter((m) => m.type === 'group').map((m) => m.id)));
+  const roots = groups.filter((g) => !nested.has(g.id));
+  return asJson ? console.log(JSON.stringify(roots.map((g) => g.id))) : roots.forEach((g) => printTree(g));
+}
+if (sub === 'members') {
+  const g = one(rest[0]); if (!g) return;
+  const list = recursive ? [...flatten(g).values()] : (g.members || []);
+  return asJson ? console.log(JSON.stringify(list)) : list.forEach((m) => console.log(label(m)));
+}
+if (sub === 'delete') {
+  const g = one(rest[0]); if (!g) return;
+  const parents = groups.filter((x) => (x.members || []).some((m) => m.type === 'group' && m.id === g.id));
+  if (parents.length) return die(`"${g.title}" is inside ${parents.map((p) => p.title).join(', ')} — remove it there first`);
+  fs.unlinkSync(path.join(DIR, `${g.id}.md`));
+  return asJson ? console.log(JSON.stringify({ ok: true, deleted: g.id })) : console.log(`✔ deleted "${g.title}"`);
+}
+die(`unknown subcommand "${sub}" — total-recall group --help`);
+}

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/project-id.mjs

@@ -0,0 +1,43 @@
+/**
+ * total-recall project-id [--json] | --all
+ *
+ * Prints this project's stable random-UUID id, creating it on first use.
+ * --all gives every registered project an id and reconciles the registry.
+ */
+import path from 'node:path';
+import { detectProjectBrain } from './agent-dir.mjs';
+import { getGlobalBrainDir } from './agent-dir.mjs';
+import { ensureProjectId, repairProjectIds } from '../core/project-id.mjs';
+
+export default async function projectIdCli(argv = []) {
+  const args = argv.filter((a) => a !== 'project-id');
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(
+      'Usage: total-recall project-id [--json]\n' +
+        '       total-recall project-id --all [--json]\n\n' +
+        "Prints this repo's random-UUID project id (created on first use, stored in\n" +
+        'config/brain.json). --all ensures every registered project has one and syncs the registry.',
+    );
+    return;
+  }
+  const json = args.includes('--json');
+  if (args.includes('--all')) {
+    const r = repairProjectIds(getGlobalBrainDir());
+    if (json) console.log(JSON.stringify(r));
+    else {
+      console.log(`  ${r.total} project(s): ${r.created} id(s) created, ${r.synced} registry row(s) synced, ${r.missing_brain} without a brain on disk`);
+    }
+    return;
+  }
+  const project = detectProjectBrain(process.cwd());
+  if (!project) {
+    console.error(`No project brain found above ${process.cwd()}`);
+    process.exit(1);
+  }
+  const { project_id, created } = ensureProjectId(project.brainDir);
+  if (json) {
+    console.log(JSON.stringify({ project_id, name: path.basename(project.projectRoot).trim(), created, path: project.projectRoot }));
+  } else {
+    console.log(project_id);
+  }
+}

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`
  */

package/src/cli/secret.mjs

@@ -57,8 +57,9 @@ import {
   deployKeyToRemotes,
 } from '../core/secrets-remote-deploy.mjs';
 import { listProviders, getProvider } from '../core/provider-catalog.mjs';
-import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
+import { resolveBrainDir, parseLayerFlag, detectProjectBrain } from './agent-dir.mjs';
 import fs from 'node:fs';
+import { ensureProjectId } from '../core/project-id.mjs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import os from 'node:os';
@@ -233,6 +234,7 @@ function printHelp() {
       --docs <url>        API docs URL
       --rotate-days <n>   Auto-rotation interval
       --auto-rotate       Enable auto-rotate flag
+    --tags <a,b,c>      Optional tags saying what the key is and what uses it
     --notes <text>
     --label <text>
     --project <path>
@@ -304,6 +306,7 @@ function parseArgs(args) {
     rotate_days: null,
     auto_rotate: false,
     notes: null,
+    tags: null,
     label: null,
     project: null,
     headscale_url: null,
@@ -390,6 +393,9 @@ function parseArgs(args) {
       case '--provider':
         out.provider = args[++i];
         break;
+      case '--tags':
+        out.tags = args[++i];
+        break;
       case '--scope':
         out.scope = args[++i];
         break;
@@ -573,6 +579,16 @@ function parseArgs(args) {
   return out;
 }
 
+/** Id of the project the command runs in (created on first use), or null outside a project. */
+function currentProjectId() {
+  try {
+    const project = detectProjectBrain(process.cwd());
+    return project ? ensureProjectId(project.brainDir).project_id : null;
+  } catch {
+    return null;
+  }
+}
+
 export default async function secretCli(argv) {
   const { layer, remainingArgs } = parseLayerFlag(argv);
   const opts = parseArgs(remainingArgs);
@@ -708,6 +724,8 @@ export default async function secretCli(argv) {
         process.exit(1);
       }
       await setSecret(brainDir, opts.key, opts.value, {
+        tags: opts.tags != null ? opts.tags : undefined,
+        project_id: currentProjectId(),
         provider: opts.provider || inferProvider(opts.key),
         scope: opts.scope,
         repos: opts.repos.length ? opts.repos : undefined,
@@ -955,6 +973,7 @@ export default async function secretCli(argv) {
       if (opts.rotate_days != null) patch.rotate_every_days = opts.rotate_days;
       if (opts.auto_rotate) patch.auto_rotate = true;
       if (opts.notes) patch.notes = opts.notes;
+      if (opts.tags != null) patch.tags = opts.tags;
       if (opts.label) patch.label = opts.label;
       if (opts.project) patch.project_path = opts.project;
       if (opts.provider) patch.provider = opts.provider;
@@ -1008,7 +1027,21 @@ export default async function secretCli(argv) {
         console.error('Usage: total-recall secret get <key>');
         process.exit(1);
       }
-      const r = await getSecret(brainDir, opts.key);
+      const project_id = currentProjectId();
+      let r = await getSecret(brainDir, opts.key, { project_id });
+      if (!r.found && layer === 'auto') {
+        // Credentials live in the global store (SSOT). From inside a project
+        // the auto layer resolves to the project store, so fall back to the
+        // global one, but only for keys bound to this repo or unbound.
+        const { globalBrainDir } = await import('../core/config.mjs');
+        const { secretMatchesTarget } = await import('../core/secrets-env-export.mjs');
+        if (globalBrainDir && globalBrainDir !== brainDir) {
+          const meta = (await listSecretsMeta(globalBrainDir)).find((k) => k.key === opts.key);
+          if (meta && secretMatchesTarget(meta, { projectPath: process.cwd(), includeGlobal: true })) {
+            r = await getSecret(globalBrainDir, opts.key, { project_id });
+          }
+        }
+      }
       if (!r.found) {
         console.error(`  Secret not found: ${opts.key}`);
         process.exit(1);
@@ -1313,7 +1346,7 @@ export default async function secretCli(argv) {
       }
       console.log(`\n  Secret audit (last ${events.length})\n`);
       for (const e of events) {
-        console.log(`  ${e.ts}  ${e.action.padEnd(8)}  ${e.key}  ${e.actor || ''}`);
+        console.log(`  ${e.ts}  ${e.action.padEnd(8)}  ${e.key}  ${e.actor || ''}${e.project_id ? `  project=${e.project_id}` : ''}`);
       }
       console.log('');
       return;