total-recall-brain 3.32.0 → 3.32.1

package/bin/total-recall.mjs

@@ -88,6 +88,11 @@ const COMMANDS = {
   brain:    'brain.mjs',
   config:   'config.mjs',
   skill:    'skill.mjs',
+  'project-id': 'project-id.mjs',
+  api:      'api.mjs',
+  brief:    'brief.mjs',
+  group:    'group.mjs',
+  groups:   'group.mjs',
   secret:   'secret.mjs',
   secrets:  'secret.mjs',
   help:     'help.mjs',
@@ -167,6 +172,19 @@ async function main() {
 
   const handlerFile = COMMANDS[command];
   if (!handlerFile) {
+    // Any HTTP API route group without a dedicated verb: `total-recall <group> <action> …`
+    try {
+      const { loadApiRoutes } = await import('../src/core/api-routes.mjs');
+      if ((await loadApiRoutes()).some((r) => r.group === command)) {
+        const { default: apiCli } = await import('../src/cli/api.mjs');
+        await apiCli(args);
+        process.exit(process.exitCode ?? 0);
+      }
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+
     // Check if it is a dynamic integration command configured in the VFS
     try {
       const { agentDir, resolveBrainLayer } = await import('../src/core/config.mjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.32.0",
+  "version": "3.32.1",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [
@@ -64,7 +64,7 @@
   "homepage": "https://github.com/gregiteen/total-recall#readme",
   "dependencies": {
     "@simplewebauthn/server": "^13.3.2",
-    "@ssss/cli": "github:gregiteen/ssss#v0.10.0",
+    "@ssss/cli": "github:gregiteen/ssss#v0.10.1",
     "bcrypt": "^6.0.0",
     "better-sqlite3": "^12.11.1",
     "cookie-parser": "^1.4.7",

package/src/cli/api.mjs

@@ -0,0 +1,133 @@
+/**
+ * total-recall api — every HTTP API route as a CLI verb.
+ *
+ *   total-recall api list [group] [--json]
+ *   total-recall api <group> <action> [positional params…] [--data '<json>'] [--query k=v]… [--json]
+ *   total-recall api call <METHOD> </api/path> [--data '<json>'] [--query k=v]…
+ *
+ * Also reachable as `total-recall <group> <action>` for any group that has no
+ * dedicated verb. Talks to the brain server named in config/brain.json.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadApiRoutes } from '../core/api-routes.mjs';
+import { detectProjectBrain, getGlobalBrainDir } from './agent-dir.mjs';
+
+function brainConnection() {
+  const dirs = [detectProjectBrain(process.cwd())?.brainDir, getGlobalBrainDir()].filter(Boolean);
+  for (const d of dirs) {
+    try {
+      const c = JSON.parse(fs.readFileSync(path.join(d, 'config', 'brain.json'), 'utf8'));
+      if (c.url) return { url: process.env.TR_BRAIN || c.url, token: process.env.TR_PAT || c.token };
+    } catch {
+      /* try next */
+    }
+  }
+  return { url: process.env.TR_BRAIN || 'http://localhost:3000', token: process.env.TR_PAT };
+}
+
+function parse(argv) {
+  const out = { pos: [], query: {}, data: undefined, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--data') out.data = argv[++i];
+    else if (a === '--query') {
+      const [k, ...v] = String(argv[++i] ?? '').split('=');
+      if (k) out.query[k] = v.join('=');
+    } else out.pos.push(a);
+  }
+  return out;
+}
+
+async function call(method, routePath, { query, data }) {
+  const { url, token } = brainConnection();
+  const qs = new URLSearchParams(query).toString();
+  const res = await fetch(`${url.replace(/\/$/, '')}${routePath}${qs ? `?${qs}` : ''}`, {
+    method,
+    headers: {
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...(data !== undefined ? { 'Content-Type': 'application/json' } : {}),
+    },
+    body: data !== undefined ? data : undefined,
+  });
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+  return { status: res.status, ok: res.ok, body };
+}
+
+function printRoutes(routes) {
+  const width = Math.max(...routes.map((r) => `${r.group} ${r.action}`.length), 10);
+  for (const r of routes) {
+    const params = r.params.map((p) => ` <${p}>`).join('');
+    console.log(`  ${`${r.group} ${r.action}${params}`.padEnd(width + 12)} ${r.method.padEnd(6)} ${r.path}`);
+  }
+}
+
+export default async function apiCli(argv = []) {
+  const opts = parse(argv[0] === 'api' ? argv.slice(1) : argv);
+  const routes = await loadApiRoutes();
+  const [first, second, ...rest] = opts.pos;
+
+  if (opts.help || !first || first === 'list') {
+    const group = first === 'list' ? second : null;
+    const shown = group ? routes.filter((r) => r.group === group) : routes;
+    if (opts.json) return console.log(JSON.stringify(shown, null, 2));
+    if (!group && !opts.help && first !== 'list') {
+      console.log('Usage: total-recall api list [group] | api <group> <action> [params] [--data json] [--query k=v] | api call <METHOD> <path>\n');
+    }
+    if (!shown.length) return console.log(`  No routes for group "${group}".`);
+    if (!group) {
+      const groups = [...new Set(routes.map((r) => r.group))];
+      console.log(`  ${routes.length} routes in ${groups.length} groups: ${groups.join(', ')}\n`);
+      if (!opts.help && first !== 'list') return;
+    }
+    return printRoutes(shown);
+  }
+
+  if (first === 'call') {
+    const [method, routePath] = [String(second || '').toUpperCase(), rest[0]];
+    if (!method || !routePath) {
+      console.error('Usage: total-recall api call <METHOD> </api/path> [--data json] [--query k=v]');
+      process.exit(1);
+    }
+    return finish(await call(method, routePath, opts), opts);
+  }
+
+  const group = first;
+  const groupRoutes = routes.filter((r) => r.group === group);
+  if (!groupRoutes.length) {
+    console.error(`Unknown API group "${group}". Run: total-recall api list`);
+    process.exit(1);
+  }
+  if (!second) return printRoutes(groupRoutes);
+  const route = groupRoutes.find((r) => r.action === second);
+  if (!route) {
+    console.error(`No "${second}" action in ${group}. Actions:`);
+    printRoutes(groupRoutes);
+    process.exit(1);
+  }
+  if (rest.length < route.params.length) {
+    console.error(`Missing parameter(s): ${route.params.slice(rest.length).map((p) => `<${p}>`).join(' ')}`);
+    process.exit(1);
+  }
+  let p = route.path;
+  route.params.forEach((name, i) => {
+    p = p.replace(`:${name}`, encodeURIComponent(rest[i]));
+  });
+  return finish(await call(route.method, p, opts), opts);
+}
+
+function finish(r, opts) {
+  console.log(typeof r.body === 'string' ? r.body : JSON.stringify(r.body, null, opts.json ? 0 : 2));
+  if (!r.ok) {
+    console.error(`HTTP ${r.status}`);
+    process.exitCode = 1;
+  }
+}

package/src/cli/brief.mjs

@@ -0,0 +1,195 @@
+/**
+ * total-recall brief
+ * Run first in every session (the global /start does): read-only brief of time, repo state, project id/groups, rules, commands, secrets health (counts only), tasks, trackers, and this repo's own start skill to follow next.
+ * Built-in (ships with the package); was a machine-local composable command.
+ */
+export default async function (args = []) {
+  // total-recall brief [--json] [--mesh]
+// Session-start brief for the repo you are in: time, repo state, project identity and groups, rules, commands, secrets health (counts only), tasks, trackers, and this repo's own start skill.
+const { spawn, spawnSync } = await import('node:child_process');
+const fs = await import('node:fs');
+const path = await import('node:path');
+
+const argl = Array.isArray(args) ? args : [];
+const asJson = argl.includes('--json');
+const withMesh = argl.includes('--mesh');
+if (argl.includes('--help') || argl.includes('-h')) {
+  console.log(`Usage: total-recall brief [--json] [--mesh]
+
+Read-only brief for the start of a session in the current repo. Composes:
+project-id, group, command list, secret catalog/rotation-due/shared/tracking-health
+(counts only, never values), task list, mesh status (--mesh adds mesh ping), git,
+the compiled rules line, docs/projects trackers, openwiki, and the repo's own
+.agent/skills/start/SKILL.md, which you follow next when it exists.`);
+  return;
+}
+
+// Run a Total Recall verb (async, bounded). Output is parsed for counts only.
+const tr = (verbArgs, ms = 45000) => new Promise((resolve) => {
+  const child = spawn(process.execPath, [process.argv[1], ...verbArgs], { cwd: process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+  let out = ''; let err = '';
+  child.stdout.on('data', (d) => { out += d; });
+  child.stderr.on('data', (d) => { err += d; });
+  const timer = setTimeout(() => { child.kill('SIGKILL'); resolve({ code: null, out, err, timedOut: true }); }, ms);
+  child.on('close', (code) => { clearTimeout(timer); resolve({ code, out, err, timedOut: false }); });
+});
+const jsonLine = (text) => {
+  for (const line of text.split('\n').reverse()) {
+    const t = line.trim();
+    if ((t.startsWith('{') || t.startsWith('[')) && !t.includes('"subsystem"')) { try { return JSON.parse(t); } catch { /* next */ } }
+  }
+  try { return JSON.parse(text.slice(text.indexOf('{'))); } catch { return null; }
+};
+const num = (text, key) => { const m = text.match(new RegExp(`${key}=(\\d+)`)); return m ? Number(m[1]) : null; };
+const git = (...a) => { const r = spawnSync('git', a, { cwd: process.cwd(), encoding: 'utf8' }); return r.status === 0 ? r.stdout.replace(/\r?\n$/, '') : null; };
+
+const now = new Date();
+const root = git('rev-parse', '--show-toplevel') || process.cwd();
+const rel = (p) => path.relative(root, p) || '.';
+
+const [pid, groupsRes, cmds, catalog, due, shared, tracking, tasks, secretList, mesh, ping] = await Promise.all([
+  tr(['project-id', '--json']),
+  tr(['group', 'list', '--json']),
+  tr(['command', 'list', '--json']),
+  tr(['secret', 'catalog']),
+  tr(['secret', 'rotation-due']),
+  tr(['secret', 'shared']),
+  tr(['secret', 'tracking-health']),
+  tr(['task', 'list']),
+  tr(['secret', 'list']),
+  tr(['mesh', 'status', '--json']),
+  withMesh ? tr(['mesh', 'ping', '--json'], 60000) : Promise.resolve(null),
+]);
+
+// Project identity + the groups that contain it (recursively).
+const project = jsonLine(pid.out);
+const groups = [];
+const groupList = jsonLine(groupsRes.out) || [];
+if (project?.project_id && Array.isArray(groupList) && groupList.length) {
+  const members = await Promise.all(groupList.map((g) => tr(['group', 'members', g.id, '--recursive', '--json'])));
+  groupList.forEach((g, i) => {
+    const list = jsonLine(members[i].out) || [];
+    if (Array.isArray(list) && list.some((m) => m.id === project.project_id)) groups.push({ id: g.id, name: g.name });
+  });
+}
+
+// Repo state.
+const status = git('status', '--porcelain');
+const repo = {
+  root,
+  branch: git('rev-parse', '--abbrev-ref', 'HEAD'),
+  dirty: status === null ? null : status.split('\n').filter(Boolean).length,
+  last_commit: git('log', '-1', '--format=%h %s (%cr)'),
+  upstream: git('rev-list', '--left-right', '--count', '@{upstream}...HEAD'),
+};
+if (repo.upstream) { const [behind, ahead] = repo.upstream.split(/\s+/).map(Number); repo.upstream = { ahead, behind, note: 'as of last fetch' }; }
+
+// Compiled rules (whatever the IDE surface says is active).
+let rules = null;
+for (const f of ['CLAUDE.md', 'AGENTS.md', 'INSTRUCTIONS.md']) {
+  const p = path.join(root, f);
+  if (!fs.existsSync(p)) continue;
+  const m = fs.readFileSync(p, 'utf8').match(/Active Rules: (\d+) invariants, (\d+) preferences, (\d+) corrections/);
+  if (m) { rules = { file: f, invariants: +m[1], preferences: +m[2], corrections: +m[3], compiled: fs.statSync(p).mtime.toISOString() }; break; }
+}
+
+// Trackers, skills, openwiki, repo start skill.
+const dirList = (p) => { try { return fs.readdirSync(p, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort(); } catch { return []; } };
+const trackers = { in_progress: dirList(path.join(root, 'docs/projects/in-progress')), planned: dirList(path.join(root, 'docs/projects/planned')) };
+const skillsDir = path.join(root, '.agent/skills');
+const skills = dirList(skillsDir).filter((s) => fs.existsSync(path.join(skillsDir, s, 'SKILL.md')));
+// A repo start skill is the repo's own; a deployed copy of the global one (repo_scoped: false) is not.
+const startSkill = ['.agent/skills/start/SKILL.md', '.claude/skills/start/SKILL.md'].map((p) => path.join(root, p))
+  .find((p) => { try { return !/^repo_scoped:\s*false/m.test(fs.readFileSync(p, 'utf8').split('\n---')[0]); } catch { return false; } }) || null;
+// OpenWiki: the repo's own wiki (openwiki/) first, then the brain copy.
+const openwiki = ['openwiki', '.agent/skills/total-recall/openwiki', '.agent/openwiki'].map((d) => path.join(root, d)).filter((d) => fs.existsSync(d)).map((d) => {
+  const pages = fs.readdirSync(d).filter((f) => f.endsWith('.md'));
+  const entry = ['quickstart.md', 'README.md'].find((f) => pages.includes(f)) || pages[0] || null;
+  const newest = pages.reduce((t, f) => Math.max(t, fs.statSync(path.join(d, f)).mtimeMs), 0);
+  return { dir: rel(d), pages: pages.length, entry: entry ? rel(path.join(d, entry)) : null, updated: newest ? new Date(newest).toISOString() : null };
+}).filter((w) => w.pages > 0);
+
+// Secrets: counts and exit codes only — never values or masked fragments.
+const secrets = {
+  keys: num(catalog.out, 'keys'),
+  providers: num(catalog.out, 'providers'),
+  rotation_due: /No secrets overdue/.test(due.out) ? 0 : (due.code === 0 ? num(catalog.out, 'rotate_due') : (num(due.out, 'due') ?? 'check')),
+  shared_values: shared.code === 0 ? 0 : (num(shared.out, 'error_groups') ?? num(shared.out, 'groups') ?? 'check'),
+  untracked: tracking.code === 0 ? 0 : (num(tracking.out, 'errors') ?? 'check'),
+};
+const cmdList = jsonLine(cmds.out) || [];
+const taskLines = tasks.out.split('\n');
+const taskCounts = { pending: taskLines.filter((l) => /^\s*\[pending\]/.test(l)).length, in_progress: taskLines.filter((l) => /^\s*\[in_progress\]/.test(l)).length };
+const meshStatus = jsonLine(mesh.out);
+const pingData = ping ? jsonLine(ping.out) : null;
+
+// Domain: what this repo can reach and what runs on its own. Names only.
+const os = await import('node:os');
+const providers = [...new Set(secretList.out.split('\n').map((l) => l.match(/^\s*•\s+\S+\s+len=\s*\d+\s+(\S+)/)?.[1]).filter(Boolean))].sort();
+const integrations = [];
+for (const [scope, dir] of [['project', path.join(root, '.agent/skills/total-recall/integrations')], ['global', path.join(os.homedir(), '.agent/skills/total-recall/integrations')]]) {
+  try { for (const f of fs.readdirSync(dir)) if (f.endsWith('.md')) integrations.push(`${f.slice(0, -3)} (${scope})`); } catch { /* none */ }
+}
+const repoName = path.basename(root);
+const automations = [];
+try {
+  const la = path.join(os.homedir(), 'Library/LaunchAgents');
+  for (const f of fs.readdirSync(la)) {
+    if (!f.endsWith('.plist')) continue;
+    const body = fs.readFileSync(path.join(la, f), 'utf8');
+    if (body.includes(root + '/') || body.includes(root + '<') || f.includes(repoName)) automations.push(`launchd ${f.replace(/\.plist$/, '')}`);
+  }
+} catch { /* not macOS */ }
+const cron = spawnSync('crontab', ['-l'], { encoding: 'utf8' });
+if (cron.status === 0) cron.stdout.split('\n').filter((l) => l.trim() && !l.startsWith('#') && l.includes(root)).forEach((l) => automations.push(`cron ${l.trim().split(/\s+/).slice(0, 5).join(' ')}`));
+let scripts = [];
+try { scripts = Object.keys(JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).scripts || {}); } catch { /* none */ }
+const launchers = fs.readdirSync(root).filter((f) => { try { const st = fs.statSync(path.join(root, f)); return st.isFile() && (st.mode & 0o111) && !f.includes('.'); } catch { return false; } });
+const domain = { providers, integrations, automations, launchers, npm_scripts: scripts };
+
+const warnings = [];
+if (!project?.project_id) warnings.push('No project brain here (total-recall init) — memory, secrets and rules are global-only.');
+if (secrets.rotation_due && secrets.rotation_due !== 0) warnings.push(`Secrets overdue for rotation: ${secrets.rotation_due} (total-recall secret rotation-due).`);
+if (secrets.shared_values && secrets.shared_values !== 0) warnings.push(`Credential values reused across keys/apps: ${secrets.shared_values} group(s) (total-recall secret shared).`);
+if (secrets.untracked && secrets.untracked !== 0) warnings.push(`Secrets without usage/account tracking: ${secrets.untracked} (total-recall secret tracking-health).`);
+if (rules && (now - new Date(rules.compiled)) > 7 * 86400000) warnings.push(`Instruction surfaces last compiled ${rules.compiled.slice(0, 10)} — run total-recall compile.`);
+for (const w of openwiki) if (w.updated && (now - new Date(w.updated)) > 30 * 86400000) warnings.push(`OpenWiki ${w.dir} last updated ${w.updated.slice(0, 10)} — may be stale.`);
+if (meshStatus && meshStatus.configured === false) warnings.push(`Mesh not configured: ${meshStatus.reason || 'unknown'}.`);
+for (const [name, r] of Object.entries({ project_id: pid, catalog, tasks, mesh })) if (r?.timedOut) warnings.push(`${name} check timed out.`);
+
+const brief = {
+  generated: { local: now.toString(), utc: now.toISOString(), timezone: Intl.DateTimeFormat().resolvedOptions().timeZone },
+  project: project ? { id: project.project_id, name: project.name, groups } : null,
+  repo, rules, skills, repo_start_skill: startSkill ? rel(startSkill) : null, openwiki, trackers,
+  domain,
+  commands: cmdList.map((c) => ({ name: c.name, scope: c.scope, risk: c.risk })),
+  secrets, tasks: taskCounts,
+  mesh: { configured: meshStatus?.configured ?? null, ping: pingData },
+  warnings,
+  next: startSkill
+    ? [`Read and follow ${rel(startSkill)} — this repo's own start steps.`]
+    : [`This repo has no start skill of its own: read ${openwiki[0]?.entry || 'the openwiki'}${skills.includes('repo-expert') ? ' and .agent/skills/repo-expert/SKILL.md' : ''} before changing code.`],
+};
+
+if (asJson) { console.log(JSON.stringify(brief, null, 2)); return; }
+
+const L = [];
+L.push(`# Brief — ${project?.name || path.basename(root)}`);
+L.push(`Time: ${now.toLocaleString()} ${brief.generated.timezone} (UTC ${brief.generated.utc})`);
+L.push(`Project id: ${project?.project_id || 'none'}${groups.length ? `  groups: ${groups.map((g) => g.name).join(', ')}` : ''}`);
+L.push(`Repo: ${repo.branch || '?'}  dirty files: ${repo.dirty ?? '?'}  last: ${repo.last_commit || '?'}${repo.upstream ? `  ahead ${repo.upstream.ahead}/behind ${repo.upstream.behind} (last fetch)` : ''}`);
+L.push(`Rules: ${rules ? `${rules.invariants} invariants, ${rules.preferences} preferences, ${rules.corrections} corrections (${rules.file}, compiled ${rules.compiled.slice(0, 16).replace('T', ' ')})` : 'no compiled surface'}`);
+L.push(`Skills (${skills.length}): ${skills.join(', ') || 'none'}`);
+L.push(`Commands (${cmdList.length}): ${cmdList.map((c) => c.name + (c.risk && !['read', 'write'].includes(c.risk) ? `[${c.risk}]` : '')).join(', ') || 'none'}`);
+L.push(`Secrets: ${secrets.keys ?? '?'} keys / ${secrets.providers ?? '?'} providers; rotation due ${secrets.rotation_due}; shared ${secrets.shared_values}; untracked ${secrets.untracked}`);
+L.push(`Providers with keys (${providers.length}): ${providers.join(', ') || 'none'}`);
+L.push(`Integrations: ${integrations.join(', ') || 'none'}  | automations: ${automations.join(', ') || 'none'}`);
+L.push(`Entry points: launchers ${launchers.map((f) => './' + f).join(' ') || 'none'}; npm scripts ${scripts.length}${scripts.length ? ` (${scripts.slice(0, 12).join(', ')}${scripts.length > 12 ? ', …' : ''})` : ''}`);
+L.push(`Tasks: ${taskCounts.pending} pending, ${taskCounts.in_progress} in progress`);
+L.push(`Mesh: ${meshStatus?.configured ? 'configured' : 'not configured'}${pingData ? ` — ping: ${JSON.stringify(pingData).slice(0, 300)}` : ' (add --mesh to ping nodes)'}`);
+L.push(`Trackers in progress: ${trackers.in_progress.join(', ') || 'none'}${trackers.planned.length ? `  | planned: ${trackers.planned.join(', ')}` : ''}`);
+L.push(`OpenWiki: ${openwiki.length ? openwiki.map((w) => `${w.entry} (${w.pages} pages, updated ${w.updated.slice(0, 10)})`).join('; ') : 'none'}`);
+if (warnings.length) { L.push('', 'Warnings:'); warnings.forEach((w) => L.push(`- ${w}`)); }
+L.push('', 'Next:'); brief.next.forEach((n) => L.push(`- ${n}`));
+console.log(L.join('\n'));
+}

package/src/cli/config.mjs

@@ -21,7 +21,12 @@ const KEY_MAP = {
 
   'daily_cap_usd': { file: 'budget', path: 'budget.daily_cap_usd', type: 'number' },
   'weekly_cap_usd': { file: 'budget', path: 'budget.weekly_cap_usd', type: 'number' },
-  'budget_enabled': { file: 'budget', path: 'budget.enabled', type: 'boolean' }
+  'budget_enabled': { file: 'budget', path: 'budget.enabled', type: 'boolean' },
+
+  // Size of each rules section in the compiled instruction files (characters).
+  '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' },
 };
 
 function resolveKeyInfo(key) {
@@ -33,7 +38,7 @@ function resolveKeyInfo(key) {
 
   // Fallback / dynamic inference
   const isBudget = key.startsWith('budget.') || key === 'budget';
-  const file = isBudget ? 'budget' : 'security';
+  const file = isBudget ? 'budget' : key.startsWith('rules.') ? 'surface' : 'security';
   const targetPath = key;
 
   let type = 'string';
@@ -131,6 +136,9 @@ export default async function configCommand(args) {
     daily_cap_usd                Cost-control daily cap (number)
     weekly_cap_usd               Cost-control weekly cap (number)
     budget_enabled               Enable/disable cost limit checks (true | false)
+    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)
     allowed_origins              CORS origins (e.g. "http://localhost:5173,http://localhost:3000")
 
   Examples:
@@ -145,12 +153,21 @@ export default async function configCommand(args) {
   const configDir = path.join(brainDir, 'config');
   const securityPath = path.join(configDir, 'security.yml');
   const budgetPath = path.join(configDir, 'budget.yml');
+  const surfacePath = path.join(configDir, 'surface.yml');
   const layerLabel = layer === 'project' ? '[project]' : layer === 'global' ? '[global]' : '[auto]';
 
   // Load configs safely
   let securityConfig = {};
   let budgetConfig = {};
+  let surfaceConfig = {};
+  const objFor = (file) => (file === 'budget' ? budgetConfig : file === 'surface' ? surfaceConfig : securityConfig);
+  const pathFor = (file) => (file === 'budget' ? budgetPath : file === 'surface' ? surfacePath : securityPath);
 
+  if (fs.existsSync(surfacePath)) {
+    try {
+      surfaceConfig = yaml.parse(fs.readFileSync(surfacePath, 'utf8')) || {};
+    } catch {}
+  }
   if (fs.existsSync(securityPath)) {
     try {
       securityConfig = yaml.parse(fs.readFileSync(securityPath, 'utf8')) || {};
@@ -166,7 +183,7 @@ export default async function configCommand(args) {
     const key = remainingArgs[1];
     if (key) {
       const info = resolveKeyInfo(key);
-      const targetObj = info.file === 'budget' ? budgetConfig : securityConfig;
+      const targetObj = objFor(info.file);
       const value = getNestedProp(targetObj, info.path);
       
       if (args.includes('--json') || args.includes('-j')) {
@@ -178,7 +195,7 @@ export default async function configCommand(args) {
       // List all known keys
       const allSettings = {};
       for (const [flatKey, info] of Object.entries(KEY_MAP)) {
-        const targetObj = info.file === 'budget' ? budgetConfig : securityConfig;
+        const targetObj = objFor(info.file);
         const val = getNestedProp(targetObj, info.path);
         allSettings[flatKey] = val !== undefined ? val : null;
       }
@@ -193,7 +210,8 @@ export default async function configCommand(args) {
         }
         console.log('\n  📍 Storage locations:');
         console.log(`     - Security: ${securityPath}`);
-        console.log(`     - Budget:   ${budgetPath}\n`);
+        console.log(`     - Budget:   ${budgetPath}`);
+        console.log(`     - Surface:  ${surfacePath}\n`);
       }
     }
     return;
@@ -214,8 +232,8 @@ export default async function configCommand(args) {
     }
 
     const info = resolveKeyInfo(key);
-    const targetObj = info.file === 'budget' ? budgetConfig : securityConfig;
-    const targetPath = info.file === 'budget' ? budgetPath : securityPath;
+    const targetObj = objFor(info.file);
+    const targetPath = pathFor(info.file);
 
     try {
       const parsedValue = castAndValidate(rawValue, info.type, info.values);

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/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/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;

package/src/core/api-routes.mjs

@@ -0,0 +1,99 @@
+/**
+ * Route table of the Total Recall HTTP API, read from the Express routers
+ * themselves so a CLI verb exists for every route without a hand-kept list.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROUTES_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../server/routes');
+
+/** Drop structured info log lines emitted by the modules the routes import, so CLI output stays parseable. */
+export function silenceInfoLogs() {
+  for (const stream of [process.stdout, process.stderr]) {
+    const write = stream.write.bind(stream);
+    stream.write = (chunk, ...rest) =>
+      typeof chunk === 'string' && /^\{"timestamp":"[^"]+","level":"(info|debug)"/.test(chunk)
+        ? true
+        : write(chunk, ...rest);
+  }
+}
+
+function isRouter(x) {
+  return typeof x === 'function' && Array.isArray(x.stack);
+}
+
+/** Verb name for a route: the static path after /api/<group>, params dropped. */
+export function actionFor(method, routePath, group) {
+  const segs = routePath.replace(/^\/api\//, '').split('/').filter(Boolean);
+  if (segs[0] === group) segs.shift();
+  const staticSegs = segs.filter((s) => !s.startsWith(':') && s !== '*');
+  const name = staticSegs.join('-');
+  if (name) return name;
+  return { GET: 'list', POST: 'create', PUT: 'update', PATCH: 'patch', DELETE: 'delete' }[method] || method.toLowerCase();
+}
+
+/**
+ * @returns {Promise<Array<{group:string, method:string, path:string, action:string, params:string[]}>>}
+ */
+export async function loadApiRoutes() {
+  silenceInfoLogs();
+  const out = [];
+  const files = fs
+    .readdirSync(ROUTES_DIR)
+    .filter((f) => f.endsWith('.mjs') && !f.endsWith('.spec.mjs') && !f.startsWith('_'))
+    .sort();
+  for (const file of files) {
+    const group = file.replace(/\.mjs$/, '');
+    let mod;
+    // Route modules log startup lines on import; keep CLI output clean.
+    const { log, info } = console;
+    console.log = console.info = () => {};
+    try {
+      mod = await import(path.join(ROUTES_DIR, file));
+    } catch {
+      continue;
+    } finally {
+      console.log = log;
+      console.info = info;
+    }
+    const routers = Object.values(mod).filter(isRouter);
+    const seen = new Set();
+    for (const router of routers) {
+      for (const layer of router.stack) {
+        if (!layer.route) continue;
+        const paths = Array.isArray(layer.route.path) ? layer.route.path : [layer.route.path];
+        for (const p of paths) {
+          if (typeof p !== 'string') continue;
+          for (const method of Object.keys(layer.route.methods).map((m) => m.toUpperCase())) {
+            const key = `${method} ${p}`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            out.push({
+              group,
+              method,
+              path: p,
+              action: actionFor(method, p, group),
+              params: [...p.matchAll(/:([A-Za-z0-9_]+)/g)].map((m) => m[1]),
+            });
+          }
+        }
+      }
+    }
+  }
+  // Make (group, action) unique: suffix the method on collisions.
+  const count = new Map();
+  for (const r of out) count.set(`${r.group}/${r.action}`, (count.get(`${r.group}/${r.action}`) || 0) + 1);
+  const used = new Map();
+  for (const r of out) {
+    const k = `${r.group}/${r.action}`;
+    if (count.get(k) > 1) {
+      let name = `${r.action}-${r.method.toLowerCase()}`;
+      const n = (used.get(`${r.group}/${name}`) || 0) + 1;
+      used.set(`${r.group}/${name}`, n);
+      if (n > 1) name = `${name}-${n}`;
+      r.action = name;
+    }
+  }
+  return out;
+}

package/src/core/project-id.mjs

@@ -0,0 +1,72 @@
+/**
+ * Stable per-project identity: a random UUID kept in the project brain's
+ * config/brain.json (`project_id`) and mirrored into the project registry.
+ * Never derived from names or paths.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+function brainJsonPath(brainDir) {
+  return path.join(brainDir, 'config', 'brain.json');
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+/** The project id stored for a project brain, or null. */
+export function readProjectId(brainDir) {
+  return readJson(brainJsonPath(brainDir), {}).project_id || null;
+}
+
+/**
+ * Return the project's id, creating a random UUID on first use.
+ * @returns {{ project_id: string, created: boolean }}
+ */
+export function ensureProjectId(brainDir) {
+  const file = brainJsonPath(brainDir);
+  const cfg = readJson(file, {});
+  if (cfg.project_id) return { project_id: cfg.project_id, created: false };
+  cfg.project_id = randomUUID();
+  writeJsonAtomic(file, cfg);
+  return { project_id: cfg.project_id, created: true };
+}
+
+/**
+ * Give every registered project an id and make the registry agree with each
+ * project's brain.json (the brain.json id wins).
+ * @returns {{ total: number, created: number, synced: number, missing_brain: number }}
+ */
+export function repairProjectIds(globalBrainDir) {
+  const registryPath = path.join(globalBrainDir, 'config', 'project-registry.json');
+  const list = readJson(registryPath, []);
+  const out = { total: 0, created: 0, synced: 0, missing_brain: 0 };
+  if (!Array.isArray(list)) return out;
+  for (const row of list) {
+    out.total++;
+    if (!row?.brainDir || !fs.existsSync(row.brainDir)) {
+      out.missing_brain++;
+      continue;
+    }
+    const { project_id, created } = ensureProjectId(row.brainDir);
+    if (created) out.created++;
+    if (row.project_id !== project_id) {
+      row.project_id = project_id;
+      out.synced++;
+    }
+  }
+  if (out.synced) writeJsonAtomic(registryPath, list);
+  return out;
+}

package/src/core/provider-catalog.mjs

@@ -464,7 +464,7 @@ function matchesOnTokenBoundary(k, stem) {
 export function providerForKeyName(keyName) {
   // Strip packaging prefixes so DEVELOPER_BRAVE_SEARCH_API_KEY → BRAVE_SEARCH_API_KEY
   let k = String(keyName || '').toUpperCase();
-  k = k.replace(/^(DEVELOPER_|VITE_|NEXT_PUBLIC_|PUBLIC_|NUXT_PUBLIC_|PORTFOLIO_|ULTRACHAT_)+/g, '');
+  k = k.replace(/^(DEVELOPER_|VITE_|NEXT_PUBLIC_|PUBLIC_|NUXT_PUBLIC_)+/g, '');
 
   // Tier 1 — exact pattern match.
   for (const p of PROVIDER_CATALOG) {

package/src/core/secrets-env-export.mjs

@@ -67,7 +67,8 @@ export function mergeEnvManagedBlock(existing, managedBody) {
 export function projectSlugFromPath(projectPath) {
   if (!projectPath) return null;
   const abs = path.resolve(projectPath);
-  return path.basename(abs);
+  // Bindings are stored trimmed, so a directory name with stray whitespace must match.
+  return path.basename(abs).trim();
 }
 
 /**
@@ -107,9 +108,7 @@ export function secretMatchesTarget(metaRow, target = {}) {
   // Explicit key list mode
   if (target.keys?.length) return true;
 
-  // Bound to this repo by slug or path (policy: at most one product repo per key)
-  // Multi-repo keys are invalid — do not project them until fixed
-  if (repos.length > 1) return false;
+  // Bound to this repo by slug or path (a key may be bound to several repos)
   if (slug && repos.some((r) => r === slug || r === '*' || r.endsWith(`/${slug}`))) {
     return true;
   }

package/src/core/secrets-store.mjs

@@ -319,15 +319,14 @@ function appendAudit(brainDir, event) {
 }
 
 /**
- * Parse repos field. Policy: 0 (developer/tooling) or exactly 1 product repo.
- * Never allow multi-repo binding — each key is unique to one repo or to developer scope.
+ * Parse repos field. A credential may be bound to zero (developer/tooling),
+ * one, or several repos; uniqueness per repo is not required.
  *
  * @param {string|string[]|null|undefined} v
- * @param {{ strict?: boolean }} opts - strict throws if >1; false collapses for read-only display
+ * @param {object} [_opts] - accepted for compatibility; there is no limit
  * @returns {string[]}
  */
-export function normalizeReposBinding(v, opts = {}) {
-  const strict = opts.strict !== false;
+export function normalizeReposBinding(v, _opts = {}) {
   let list = [];
   if (Array.isArray(v)) {
     list = [...new Set(v.map(String).map((s) => s.trim()).filter(Boolean))];
@@ -341,18 +340,21 @@ export function normalizeReposBinding(v, opts = {}) {
       ),
     ];
   }
-  if (strict && list.length > 1) {
-    throw new Error(`A credential can be bound to at most ONE repo. Got ${list.length}: ${list.join(', ')}`);
-  }
   return list;
 }
 
 /**
- * True when meta has multi-repo violation (legacy data).
+ * Multi-repo binding is allowed, so this is never a violation. Kept because
+ * callers still read the field.
  */
-export function isMultiRepoViolation(meta = {}) {
-  const repos = Array.isArray(meta.repos) ? meta.repos.filter(Boolean) : [];
-  return repos.length > 1;
+export function isMultiRepoViolation(_meta = {}) {
+  return false;
+}
+
+/** Lowercase, de-duplicated tag list from an array or comma/space separated string. */
+export function normalizeTags(v) {
+  const raw = Array.isArray(v) ? v : String(v ?? '').split(/[,;\s]+/);
+  return [...new Set(raw.map((t) => String(t).trim().toLowerCase()).filter(Boolean))];
 }
 
 /**
@@ -370,8 +372,9 @@ export function mergeSecretMeta(prev = {}, patch = {}) {
   assign('scope', (v) => (v === 'project' ? 'project' : 'global'));
   assign('provider', (v) => (v ? String(v).toLowerCase() : null));
   assign('label', (v) => (v == null ? null : String(v)));
-  // Writes only — at most one product repo; empty = Developer secrets
-  assign('repos', (v) => normalizeReposBinding(v, { strict: true }));
+  // empty = Developer secrets
+  assign('repos', (v) => normalizeReposBinding(v));
+  assign('tags', normalizeTags);
   assign('subscription_tier', (v) => (v == null || v === '' ? null : String(v)));
   assign('monthly_cost_usd', (v) => (v == null || v === '' ? null : Number(v)));
   assign('monthly_cap_usd', (v) => (v == null || v === '' ? null : Number(v)));
@@ -478,19 +481,13 @@ export function buildSharedValueIndex(rows = []) {
     const multiKey = keys.length > 1;
     // Error unless every member is operator-waived
     const allOk = members.every((m) => m.shared_value_ok === true);
-    let severity = 'error';
-    let error = null;
-    if (allOk) {
-      severity = 'ok';
-      error = null;
-    } else if (multiApp) {
-      severity = 'error';
-      error = `SHARED CREDENTIAL across apps/repos [${apps.join(', ')}] as keys [${keys.join(', ')}]. Issue a unique API key per app and re-bind.`;
-    } else {
-      // Same app/developer but duplicated under multiple secret names — still force unique
-      severity = 'error';
-      error = `SHARED CREDENTIAL value stored under ${keys.length} secret names [${keys.join(', ')}] (app=${apps[0]}). Use one key name or issue distinct values per purpose.`;
-    }
+    // Sharing a value across keys or repos is allowed; it is reported for
+    // information only and never counts as unhealthy.
+    void allOk;
+    const severity = 'info';
+    const error = multiApp
+      ? `Shared value across [${apps.join(', ')}] as keys [${keys.join(', ')}] (allowed).`
+      : `Same value stored under ${keys.length} secret names [${keys.join(', ')}] (allowed).`;
 
     const group = {
       fingerprint: fp.slice(0, 12),
@@ -582,8 +579,9 @@ export async function listSecretsMeta(brainDir) {
       label: m.label || null,
       repos,
       repo: repos.length === 1 ? repos[0] : null,
-      multi_repo_error: isMultiRepoViolation(m),
-      binding_error: isMultiRepoViolation(m) ? `Legacy data error: Bound to ${repos.length} repos. Must be resolved to 1 or 0.` : null,
+      multi_repo_error: false,
+      binding_error: null,
+      tags: Array.isArray(m.tags) ? m.tags : [],
       project_path: m.project_path || null,
       subscription_tier: m.subscription_tier || null,
       monthly_cost_usd: m.monthly_cost_usd ?? null,
@@ -838,6 +836,7 @@ export async function setSecret(brainDir, key, value, opts = {}) {
     scope: opts.scope || prev.scope || 'global',
     provider: opts.provider || prev.provider || null,
     repos: opts.repos !== undefined ? opts.repos : prev.repos,
+    tags: opts.tags !== undefined ? opts.tags : prev.tags,
     subscription_tier: opts.subscription_tier !== undefined ? opts.subscription_tier : prev.subscription_tier,
     monthly_cost_usd: opts.monthly_cost_usd !== undefined ? opts.monthly_cost_usd : prev.monthly_cost_usd,
     monthly_cap_usd: opts.monthly_cap_usd !== undefined ? opts.monthly_cap_usd : prev.monthly_cap_usd,
@@ -860,6 +859,7 @@ export async function setSecret(brainDir, key, value, opts = {}) {
     scope: secrets[META_KEY].keys[key].scope,
     provider: secrets[META_KEY].keys[key].provider,
     actor: opts.actor || 'cli',
+    project_id: opts.project_id || null,
   });
 
   // First-time set only: optionally queue product-level API research (not raw key-name scraping).
@@ -907,6 +907,7 @@ export async function getSecret(brainDir, key, opts = {}) {
     action: opts.action || 'get',
     key,
     actor: opts.actor || 'cli',
+    project_id: opts.project_id || null,
   });
   return { found: true, key, value: secrets[key] };
 }

package/src/core/source-adapters.mjs

@@ -16,7 +16,7 @@ import {
 /**
  * Research Source Adapters — Real Service Integrations
  *
- * Env vars (matching UltraChat conventions — already set in your environment):
+ * Env vars (read from the environment or the secret store):
  *   BRAVE_SEARCH_API_KEY  — Brave Search API (primary web search)
  *   SERPER_API_KEY        — Serper.dev (fallback web search)
  *   GITHUB_TOKEN          — GitHub REST API (higher rate limits)
@@ -278,7 +278,7 @@ export async function braveSearch(query, config, count = 5) {
 
 /**
  * Search the web using Serper.dev API (fallback when Brave unavailable).
- * Uses SERPER_API_KEY — already defined in UltraChat .env.local.
+ * Uses SERPER_API_KEY from the environment or the secret store.
  * https://serper.dev/
  *
  * @param {string} query

package/src/core/surface.mjs

@@ -13,6 +13,7 @@ import {
 import { assemblePluginContexts } from './plugin-context.mjs';
 import { selectResearchBriefs, formatResearchBriefs } from './research-surface.mjs';
 import { loadQueue } from './research-queue.mjs';
+import yaml from 'yaml';
 import { brainDir as globalBrainDir, globalAgentDir } from './config.mjs';
 import { listSurfaceCommands, buildCommandsSection, surfaceInputsHash } from './command-surface.mjs';
 import { fileURLToPath } from 'url';
@@ -355,6 +356,31 @@ export function buildResearchSection(nodes = [], { projectRoot, queueItems, rese
   }
 }
 
+const DEFAULT_RULE_BUDGET = { invariants: 9000, preferences: 4000, corrections: 8000 };
+
+/** Rule-section budgets (characters) from surface.yml files and the environment. */
+export function readRuleBudgets(skillsDir) {
+  const out = {};
+  const dirs = [skillsDir ? path.join(skillsDir, 'total-recall') : null, globalBrainDir].filter(Boolean);
+  for (const dir of dirs.reverse()) {
+    try {
+      const cfg = yaml.parse(fs.readFileSync(path.join(dir, 'config', 'surface.yml'), 'utf8')) || {};
+      for (const k of Object.keys(DEFAULT_RULE_BUDGET)) {
+        const v = Number(cfg?.rules?.[`${k}_budget_chars`]);
+        if (Number.isFinite(v) && v > 0) out[k] = v;
+      }
+    } catch {
+      /* no surface.yml in this brain */
+    }
+  }
+  try {
+    Object.assign(out, JSON.parse(process.env.TR_RULE_BUDGET_CHARS || '{}'));
+  } catch {
+    /* ignore a malformed override */
+  }
+  return out;
+}
+
 export async function buildRulesBlock(skillsDir, nodes = [], { consumer = 'ide', derivedDir, force = false, vaultDir, projectRoot } = {}) {
   // 1. Filter expired rules. Compilation must remain a pure projection step;
   // archival is handled by explicit memory operations.
@@ -401,7 +427,7 @@ export async function buildRulesBlock(skillsDir, nodes = [], { consumer = 'ide',
   const rawCorrections = nodes.filter(n => n.category === 'anti-patterns' && n.status === 'active' && !isExpired(n) && isImportant(n) && isRelevantToRepo(n));
 
   // Deduplicate nodes by normalized content key and rank by priority/importance
-  const deduplicateAndRankNodes = (list, maxCount = 15) => {
+  const deduplicateAndRankNodes = (list) => {
     const seen = new Map();
     const deduped = [];
     
@@ -427,40 +453,62 @@ export async function buildRulesBlock(skillsDir, nodes = [], { consumer = 'ide',
         deduped.push(n);
       }
     }
-    const kept = deduped.slice(0, maxCount);
-    kept.omitted = deduped.length - kept.length;
-    return kept;
+    return deduped;
   };
 
-  const invariants = deduplicateAndRankNodes(rawInvariants, 15);
-  const preferences = deduplicateAndRankNodes(rawPreferences, 10);
-  const corrections = deduplicateAndRankNodes(rawCorrections, 15);
-  const omittedNote = (list, label, category) => (list.omitted > 0
-    ? `\n\n_${list.omitted} more ${label} not shown (section cap). Search them with \`npx total-recall recall "<topic>" --category ${category}\`._`
-    : '');
-
-  const formatNodes = async (list) => {
-    const formatted = [];
+  const invariants = deduplicateAndRankNodes(rawInvariants);
+  const preferences = deduplicateAndRankNodes(rawPreferences);
+  const corrections = deduplicateAndRankNodes(rawCorrections);
+
+  // Rules are never dropped. Each section has a character budget: rules that
+  // must always be seen (absolute priority or MUST / MUST NOT) are always
+  // written in full; the rest are written in full while the budget lasts and
+  // then as one-line entries (title and slug). Budgets can be raised with
+  // TR_RULE_BUDGET_CHARS='{"invariants":15000,"preferences":6000,"corrections":12000}'.
+  // Precedence: TR_RULE_BUDGET_CHARS, then this brain's config/surface.yml,
+  // then the global brain's, then the defaults.
+  const budgetCfg = readRuleBudgets(skillsDir);
+  const RULE_BUDGET = { ...DEFAULT_RULE_BUDGET, ...budgetCfg };
+  const mustSee = (n) => n.priority === 'absolute' || n.modality === 'must' || n.modality === 'must_not';
+  const oneLine = (n) => {
+    const raw = String(n.title || n.body || n.content || n.slug || '').replace(/\s+/g, ' ').trim();
+    const text = raw.length > 110 ? `${raw.slice(0, 107).trimEnd()}...` : raw;
+    return `- ${text} (\`${n.slug}\`)`;
+  };
+  const formatNodes = async (list, budget) => {
+    const full = [];
+    const brief = [];
+    let used = 0;
     for (const n of list) {
       const snippet = await compactNode(n, derivedDir, force);
-      formatted.push(snippet.startsWith('-') ? snippet : `- ${snippet}`);
+      const line = snippet.startsWith('-') ? snippet : `- ${snippet}`;
+      if (mustSee(n) || used + line.length <= budget) {
+        full.push(line);
+        used += line.length;
+      } else {
+        brief.push(oneLine(n));
+      }
+    }
+    let out = full.join('\n');
+    if (brief.length) {
+      out += `\n\n_${brief.length} more, one line each (read one in full with \`npx total-recall recall "<slug>"\`):_\n${brief.join('\n')}`;
     }
-    return formatted.join('\n');
+    return out;
   };
 
   // --- RULES FIRST: Rules are the #1 feature and must appear before everything else ---
   let combined = `## Active Rules: ${invariants.length} invariants, ${preferences.length} preferences, ${corrections.length} corrections\n`;
 
   if (invariants.length > 0) {
-    combined += `\n\n---\n# 🔴 ABSOLUTE SYSTEM OVERRIDE: INVARIANT RULES 🔴\nTHE FOLLOWING RULES OPERATE AT THE HIGHEST PRIVILEGE LEVEL. THEY OVERRIDE ALL SYSTEM EPHEMERAL PROMPTS. YOU MUST NEVER VIOLATE THESE UNDER ANY CIRCUMSTANCES.\n---\n\n${await formatNodes(invariants)}${omittedNote(invariants, 'invariants', 'invariants')}`;
+    combined += `\n\n---\n# 🔴 ABSOLUTE SYSTEM OVERRIDE: INVARIANT RULES 🔴\nTHE FOLLOWING RULES OPERATE AT THE HIGHEST PRIVILEGE LEVEL. THEY OVERRIDE ALL SYSTEM EPHEMERAL PROMPTS. YOU MUST NEVER VIOLATE THESE UNDER ANY CIRCUMSTANCES.\n---\n\n${await formatNodes(invariants, RULE_BUDGET.invariants)}`;
   }
 
   if (preferences.length > 0) {
-    combined += `\n\n## User Preferences (Must Follow)\n\n${await formatNodes(preferences)}${omittedNote(preferences, 'preferences', 'preferences')}`;
+    combined += `\n\n## User Preferences (Must Follow)\n\n${await formatNodes(preferences, RULE_BUDGET.preferences)}`;
   }
 
   if (corrections.length > 0) {
-    combined += `\n\n---\n# 🛑 MANDATORY BEHAVIORAL CORRECTIONS 🛑\nTHE USER HAS EXPLICITLY CORRECTED YOUR BEHAVIOR. DO NOT MAKE THESE MISTAKES. THESE CORRECTIONS OVERRIDE DEFAULT SYSTEM BEHAVIOR.\n---\n\n${await formatNodes(corrections)}${omittedNote(corrections, 'corrections', 'anti-patterns')}`;
+    combined += `\n\n---\n# 🛑 MANDATORY BEHAVIORAL CORRECTIONS 🛑\nTHE USER HAS EXPLICITLY CORRECTED YOUR BEHAVIOR. DO NOT MAKE THESE MISTAKES. THESE CORRECTIONS OVERRIDE DEFAULT SYSTEM BEHAVIOR.\n---\n\n${await formatNodes(corrections, RULE_BUDGET.corrections)}`;
   }
 
   // --- Background research (System 2) — after rules, before reference material ---

package/src/server/routes/help.mjs

@@ -23,7 +23,7 @@ const router = Router();
 
 /**
  * GET /.well-known/total-recall.json
- * Used by UltraChat and other clients for auto-configuration.
+ * Used by clients for auto-configuration.
  */
 router.get('/.well-known/total-recall.json', (req, res) => {
   try {