total-recall-brain 3.31.2 → 3.32.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/command.mjs

@@ -1,17 +1,166 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawn } from 'node:child_process';
 import { resolveBrainLayer } from '../core/config.mjs';
+import { isSafeRelativePath, validatePluginManifest } from '../core/plugin-loader.mjs';
+
+const COMMAND_NAME = /^[a-z][a-z0-9-]{0,63}$/;
+
+function safeCommandName(name) {
+  if (!COMMAND_NAME.test(name || '')) throw new Error('Command name must be lowercase kebab-case (1–64 characters)');
+  return name;
+}
+
+/** Generate a composable command from one validated plugin manifest entry. */
+export function generatePluginCommand(pluginDir, name, commandsDir) {
+  safeCommandName(name);
+  const root = fs.realpathSync(pluginDir);
+  const manifestPath = path.join(root, 'plugin.json');
+  if (!fs.statSync(manifestPath).isFile() || fs.lstatSync(manifestPath).isSymbolicLink()) {
+    throw new Error('Plugin manifest must be a regular file');
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const validation = validatePluginManifest(manifest);
+  if (!validation.valid) throw new Error(`Invalid plugin manifest: ${validation.errors.join('; ')}`);
+  const spec = (manifest.commands || []).find((entry) => entry.name === name);
+  if (!spec) throw new Error(`Plugin '${manifest.id}' has no command '${name}'`);
+  if (!isSafeRelativePath(spec.handler) || spec.handler.includes('\\') || !spec.handler.endsWith('.mjs')) {
+    throw new Error(`Command '${name}' needs a safe .mjs handler path`);
+  }
+  const handlerPath = path.resolve(root, spec.handler);
+  const relative = path.relative(root, handlerPath);
+  if (!relative || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)
+      || !fs.statSync(handlerPath).isFile() || fs.realpathSync(handlerPath) !== handlerPath) {
+    throw new Error(`Command '${name}' handler must be a regular file inside the plugin`);
+  }
+  fs.mkdirSync(commandsDir, { recursive: true });
+  const commandPath = path.join(commandsDir, `${name}.mjs`);
+  if (fs.existsSync(commandPath)) throw new Error(`Command '${name}' already exists`);
+  const handlerUrl = pathToFileURL(handlerPath).href;
+  const content = `// Generated from plugin ${manifest.id}; edit the plugin manifest/handler, then regenerate.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const name = ${JSON.stringify(name)};
+const description = ${JSON.stringify(spec.description || '')};
+const handlerUrl = ${JSON.stringify(handlerUrl)};
+const backgroundAllowed = ${spec.background === true};
+
+export async function run(argv = process.argv, direct = false) {
+  const args = argv.slice(direct ? 2 : 3);
+  const json = args.includes('--json');
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: total-recall ' + name + ' [args…] [--json]' + (backgroundAllowed ? ' [--background]' : '') + '\\n\\n' + description);
+    return;
+  }
+  try {
+    if (args.includes('--background')) {
+      if (!backgroundAllowed) throw Object.assign(new Error('Background execution is not enabled for this command'), { exitCode: 2 });
+      const reports = path.join(path.dirname(fileURLToPath(import.meta.url)), 'reports');
+      fs.mkdirSync(reports, { recursive: true, mode: 0o700 });
+      const report = path.join(reports, name + '-' + crypto.randomUUID() + '.log');
+      const fd = fs.openSync(report, 'wx', 0o600);
+      const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...args.filter((a) => a !== '--background')], {
+        detached: true, stdio: ['ignore', fd, fd]
+      });
+      fs.closeSync(fd);
+      child.unref();
+      const status = { ok: true, pid: child.pid, report };
+      if (json) console.log(JSON.stringify(status));
+      else console.log('Started ' + name + ' in background (pid ' + child.pid + '); report: ' + report);
+      return status;
+    }
+    const handler = await import(handlerUrl);
+    const entry = handler.run || handler.default;
+    if (typeof entry !== 'function') throw new Error('Plugin command handler must export run() or default function');
+    const handlerArgs = args.filter((arg) => arg !== '--json');
+    const result = await entry(handler.run ? [process.execPath, 'total-recall', name, ...handlerArgs] : handlerArgs);
+    const exitCode = Number.isInteger(result?.exitCode) ? result.exitCode : 0;
+    if (json) console.log(JSON.stringify({ ok: exitCode === 0, exit_code: exitCode, result: result?.data ?? result ?? null }));
+    process.exitCode = exitCode;
+    return result;
+  } catch (error) {
+    const exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+    if (json) console.log(JSON.stringify({ ok: false, exit_code: exitCode, error: error.message }));
+    else console.error(error.message);
+    process.exitCode = exitCode;
+  }
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await run(process.argv, true);
+}
+`;
+  fs.writeFileSync(commandPath, content, { encoding: 'utf8', flag: 'wx', mode: 0o644 });
+  return commandPath;
+}
+
+/**
+ * Generate `total-recall <name> config|<collection>|detect|init` for a layered
+ * skill deployed in the repo that owns `commandsDir` (<repo>/.agent/commands).
+ * The wrapper holds no config logic: it delegates to the running Total Recall
+ * CLI, so the layer contract in the skill core stays the only source of truth.
+ */
+export function generateSkillConfigCommand(skillId, name, commandsDir) {
+  safeCommandName(name);
+  safeCommandName(skillId);
+  const repoRoot = path.resolve(commandsDir, '..', '..');
+  const schemaPath = path.join(repoRoot, '.agent', 'skills', skillId, 'core', 'config.schema.json');
+  if (!fs.existsSync(schemaPath) || !fs.statSync(schemaPath).isFile()) {
+    throw new Error(`Skill '${skillId}' in ${repoRoot} has no core/config.schema.json; deploy the layered skill first`);
+  }
+  fs.mkdirSync(commandsDir, { recursive: true });
+  const commandPath = path.join(commandsDir, `${name}.mjs`);
+  if (fs.existsSync(commandPath)) throw new Error(`Command '${name}' already exists`);
+  const fallbackModule = pathToFileURL(path.join(path.dirname(fileURLToPath(import.meta.url)), 'skill-config.mjs')).href;
+  const content = `// Generated repo-layer config command for skill ${skillId}; the contract is .agent/skills/${skillId}/core/config.schema.json.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const skillId = ${JSON.stringify(skillId)};
+const name = ${JSON.stringify(name)};
+const fallbackModule = ${JSON.stringify(fallbackModule)};
+
+// Prefer the Total Recall install that is running this command, so upgrades apply.
+function configModule() {
+  try {
+    const bin = fs.realpathSync(process.argv[1]);
+    const candidate = path.join(path.dirname(path.dirname(bin)), 'src', 'cli', 'skill-config.mjs');
+    if (path.basename(bin) === 'total-recall.mjs' && fs.existsSync(candidate)) return pathToFileURL(candidate).href;
+  } catch { /* fall back to the generating install */ }
+  return fallbackModule;
+}
+
+export async function run(argv = process.argv) {
+  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const { runSkillConfig } = await import(configModule());
+  return runSkillConfig(skillId, argv.slice(3), { repoRoot, prefix: 'total-recall ' + name });
+}
+`;
+  fs.writeFileSync(commandPath, content, { encoding: 'utf8', flag: 'wx', mode: 0o644 });
+  return commandPath;
+}
 
 function printHelp() {
   console.log(`
   total-recall command — Manage custom composable CLI commands
 
   Usage:
-    total-recall command create <name> "<code>" [--global]   Create a new custom CLI command
+    total-recall command create <name> "<code>" [--global] [--description "<when to use>"] [--risk <class>]
+                                                             Create a custom CLI command (listed in instruction surfaces)
+    total-recall command create <name> --from-plugin <dir>   Generate from a plugin manifest
+    total-recall command create <name> --config-for-skill <id>
+                                                             Generate repo-layer config verbs for a
+                                                             layered skill deployed in this repo
     total-recall command read <name> [--global]              Read the code of a custom CLI command
     total-recall command update <name> "<code>" [--global]   Update an existing custom CLI command
     total-recall command remove <name> [--global]            Remove a custom CLI command
-    total-recall command list [--global]                     List custom CLI commands
+    total-recall command list [--global] [--json]            List custom CLI commands
 
   Examples:
     npx total-recall command create hello "console.log('Hello from the brain!');"
@@ -49,9 +198,66 @@ export async function run(argv = []) {
   return commandCmd(args);
 }
 
+/**
+ * Built-in verbs resolve before custom commands (bin/total-recall.mjs), so a
+ * custom command with a built-in name could never run. Read the names from the
+ * dispatcher itself so this list cannot drift.
+ */
+export function builtinCommandNames() {
+  try {
+    const bin = fs.readFileSync(new URL('../../bin/total-recall.mjs', import.meta.url), 'utf8');
+    const block = bin.match(/^const COMMANDS = \{([\s\S]*?)^\};/m)?.[1] || '';
+    return new Set([...block.matchAll(/^\s+'?([a-z][a-z0-9-]*)'?\s*:/gm)].map((m) => m[1]));
+  } catch {
+    return new Set();
+  }
+}
+
+const RISKS = new Set(['read', 'write', 'money', 'dns-cert', 'production-deploy', 'secret-revoke']);
+
+/** Pull `--flag <value>` pairs out of argv so positional parsing is unaffected. */
+function takeOption(list, flag) {
+  const i = list.indexOf(flag);
+  if (i === -1) return { list, value: undefined };
+  return { list: [...list.slice(0, i), ...list.slice(i + 2)], value: list[i + 1] };
+}
+
+function headerTags(description, risk) {
+  const one = (v) => String(v).replace(/[\r\n]+/g, ' ').trim();
+  return (description ? `// @description ${one(description)}\n` : '') + (risk ? `// @risk ${risk}\n` : '');
+}
+
+function existingTag(file, key) {
+  try { return fs.readFileSync(file, 'utf8').match(new RegExp(`^// @${key} (.+)$`, 'm'))?.[1] || undefined; } catch { return undefined; }
+}
+
+/**
+ * Composable instructions: the surfaces list every command, so any change to
+ * the command set recompiles them (project layer, or every project for global).
+ */
+function recompileSurfaces(isGlobal) {
+  if (process.env.TR_COMMAND_NO_COMPILE === '1' || !process.argv[1]) return;
+  try {
+    const child = spawn(process.execPath, [process.argv[1], 'compile', isGlobal ? '--global' : '--project'], { detached: true, stdio: 'ignore' });
+    child.unref();
+    console.log('  ⏳ Instruction surfaces recompiling in the background (command list updated).');
+  } catch (error) {
+    console.warn(`  ⚠️  Command saved, but surface recompile failed to start: ${error.message}`);
+  }
+}
+
 export default async function commandCmd(rawArgs = []) {
   const isGlobal = rawArgs.includes('--global') || rawArgs.includes('-g');
-  const cleanArgs = rawArgs.filter(a => a !== '--global' && a !== '-g');
+  const asJson = rawArgs.includes('--json');
+  let cleanArgs = rawArgs.filter(a => a !== '--global' && a !== '-g' && a !== '--json');
+  let description; let risk;
+  ({ list: cleanArgs, value: description } = takeOption(cleanArgs, '--description'));
+  ({ list: cleanArgs, value: risk } = takeOption(cleanArgs, '--risk'));
+  if (risk !== undefined && !RISKS.has(risk)) {
+    console.error(`Error: --risk must be one of ${[...RISKS].join(', ')}`);
+    process.exitCode = 2;
+    return;
+  }
 
   const action = cleanArgs[0];
   const name = cleanArgs[1];
@@ -67,9 +273,50 @@ export default async function commandCmd(rawArgs = []) {
     process.exit(1);
   }
 
+  if (name) {
+    try { safeCommandName(name); }
+    catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 2; return; }
+  }
+
   const commandsDir = resolveTargetDir(isGlobal);
 
   if (action === 'create') {
+    if (builtinCommandNames().has(name)) {
+      console.error(`Error: '${name}' is a built-in Total Recall command; a custom command with that name could never run. Choose another name.`);
+      process.exitCode = 2;
+      return;
+    }
+    const otherDir = resolveTargetDir(!isGlobal);
+    if (path.resolve(otherDir) !== path.resolve(commandsDir) && fs.existsSync(path.join(otherDir, `${name}.mjs`))) {
+      console.warn(`  ⚠️  A ${isGlobal ? 'project' : 'global'} command '${name}' already exists (${otherDir}); the project one runs first here.`);
+    }
+    const forSkill = cleanArgs.indexOf('--config-for-skill');
+    if (forSkill !== -1) {
+      try {
+        if (isGlobal) throw new Error('Repo-layer config commands belong to one repository; omit --global');
+        if (!cleanArgs[forSkill + 1]) throw new Error('Missing skill id after --config-for-skill');
+        const commandPath = generateSkillConfigCommand(cleanArgs[forSkill + 1], name, commandsDir);
+        console.log(`✔ Generated npx total-recall ${name} config|detect|init; saved to: ${commandPath}`);
+        recompileSurfaces(isGlobal);
+      } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+    const fromPlugin = cleanArgs.indexOf('--from-plugin');
+    if (fromPlugin !== -1) {
+      try {
+        if (!cleanArgs[fromPlugin + 1]) throw new Error('Missing plugin directory after --from-plugin');
+        const commandPath = generatePluginCommand(cleanArgs[fromPlugin + 1], name, commandsDir);
+        console.log(`✔ Generated npx total-recall ${name} from plugin; saved to: ${commandPath}`);
+        recompileSurfaces(isGlobal);
+      } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
     const code = cleanArgs[2];
     if (!code) {
       console.error(`Error: Missing code snippet for the command.`);
@@ -82,10 +329,15 @@ export default async function commandCmd(rawArgs = []) {
     }
 
     const commandPath = path.join(commandsDir, `${name}.mjs`);
+    if (fs.existsSync(commandPath)) {
+      console.error(`Error: Custom command '${name}' already exists.`);
+      process.exitCode = 1;
+      return;
+    }
     
     // Wrap code in an exported run/default function for composable CLI execution
     const fileContent = `// Auto-generated custom CLI command: ${name}
-export async function run(argv = []) {
+${headerTags(description, risk)}export async function run(argv = []) {
   const args = Array.isArray(argv) ? argv.slice(3) : [];
   ${code}
 }
@@ -97,6 +349,8 @@ export default async function (args = []) {
     fs.writeFileSync(commandPath, fileContent, 'utf8');
     console.log(`\x1b[32m✔ Successfully created custom command: \x1b[1mnpx total-recall ${name}\x1b[0m`);
     console.log(`  Saved to: ${commandPath}`);
+    if (!description) console.log('  Tip: add --description "<when to use it>" so the instruction surfaces say when to use this command.');
+    recompileSurfaces(isGlobal);
   } else if (action === 'read') {
     const commandPath = path.join(commandsDir, `${name}.mjs`);
     if (fs.existsSync(commandPath)) {
@@ -119,8 +373,11 @@ export default async function (args = []) {
       process.exit(1);
     }
 
+    // Keep the declared description/risk unless the update replaces them.
+    const keptDescription = description ?? existingTag(commandPath, 'description');
+    const keptRisk = risk ?? existingTag(commandPath, 'risk');
     const fileContent = `// Auto-generated custom CLI command: ${name}
-export async function run(argv = []) {
+${headerTags(keptDescription, keptRisk)}export async function run(argv = []) {
   const args = Array.isArray(argv) ? argv.slice(3) : [];
   ${code}
 }
@@ -132,6 +389,7 @@ export default async function (args = []) {
     fs.writeFileSync(commandPath, fileContent, 'utf8');
     console.log(`\x1b[32m✔ Successfully updated custom command: \x1b[1m${name}\x1b[0m`);
     console.log(`  Saved to: ${commandPath}`);
+    recompileSurfaces(isGlobal);
   } else if (action === 'list') {
     const targets = isGlobal 
       ? [{ label: 'Global', dir: resolveTargetDir(true) }]
@@ -140,6 +398,11 @@ export default async function (args = []) {
           { label: 'Global', dir: resolveTargetDir(true) }
         ];
 
+    if (asJson) {
+      const { listSurfaceCommands } = await import('../core/command-surface.mjs');
+      console.log(JSON.stringify(listSurfaceCommands(targets.map((t) => ({ scope: t.label.toLowerCase(), dir: t.dir })))));
+      return;
+    }
     let foundAny = false;
     for (const t of targets) {
       if (fs.existsSync(t.dir)) {
@@ -161,6 +424,7 @@ export default async function (args = []) {
     if (fs.existsSync(commandPath)) {
       fs.unlinkSync(commandPath);
       console.log(`\x1b[32m✔ Successfully removed custom command: \x1b[1m${name}\x1b[0m`);
+      recompileSurfaces(isGlobal);
     } else {
       console.error(`Error: Custom command '${name}' does not exist.`);
       process.exit(1);

package/src/cli/config.mjs

@@ -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/connect.mjs

@@ -10,7 +10,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Resolve templates dir relative to this file (src/cli/ → ../../templates/)
 const TEMPLATES_DIR = path.resolve(__dirname, '..', '..', 'templates');
 
-const CLIENTS = {
+export const CLIENTS = {
   vscode: {
     label: 'VS Code Copilot',
     mode: 'file',