total-recall-brain 3.40.7 → 3.41.1

package/src/server/routes/invoke.mjs

@@ -0,0 +1,314 @@
+/** Optional developer API. Explicit grants precede every owner execution. */
+import { Router } from 'express';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { requireAuth } from '../auth.mjs';
+import { loadKeys, keyHasScope } from '../keys.mjs';
+import { brainDir, globalBrainDir } from '../../core/config.mjs';
+import { logger } from '../../core/logger.mjs';
+import crypto from 'node:crypto';
+import { appendVfsEvent } from '../../core/ssss-operation-service.mjs';
+import { CLI_COMMANDS } from '../../core/cli-commands.mjs';
+import { buildPluginCatalog } from '../../core/plugin-catalog.mjs';
+import { listSurfaceCommands } from '../../core/command-surface.mjs';
+import { composedCommandDirectories } from '../../core/composed-command-resolution.mjs';
+import { invokeAuthority, authorizeInvoke, operationAllowed } from '../invoke-policy.mjs';
+import { restrictedBrainTargets } from '../invoke-targets.mjs';
+import { INVOKE_LIMITS, InvokeError, executeInvokeChild, requireSuccessfulRun, invokeEnvironment, absoluteTarget } from '../invoke-execution.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+// Share across router instances in this server; do not race projection refreshes.
+const mutatingBrains = new Set();
+export const OPERATIONS = Object.freeze(Object.fromEntries(Object.entries({
+  capabilities: { scope: null, family: 'introspection' },
+  'cli.run': { scope: 'sandbox:run', family: 'cli' },
+  'ssss.read': { scope: 'ssss:read', family: 'ssss' },
+  'ssss.write': { scope: 'ssss:write', family: 'ssss' },
+  'composable.list': { scope: 'config:read', family: 'composable' },
+  'composable.run': { scope: 'sandbox:run', family: 'composable' },
+  'decision.run': { scope: 'memory:read', family: 'decision' },
+  'decision.predict': { scope: 'memory:read', family: 'decision' },
+}).map(([name, def]) => [name, Object.freeze(def)])));
+
+const fail = (res, status, operation, code, message, extra = {}) => res.status(status).json({
+  ok: false, operation, result: null, error: { code, message }, ...extra,
+});
+
+/** Only scopes that can execute are advertised. */
+function capabilitiesFor(authority, limits = INVOKE_LIMITS, targets = ['server']) {
+  const families = {};
+  for (const [name, def] of Object.entries(OPERATIONS)) {
+    if (!operationAllowed(authority, name, def.scope, targets)) continue;
+    (families[def.family] ||= []).push({ operation: name, scope: def.scope });
+  }
+  return { operations: families, families: Object.keys(families), mode: authority.mode,
+    targets: authority.mode === 'full' ? 'host' : targets,
+    credentials: authority.mode === 'full' ? 'host-auth-owner' : [],
+    provider_spending: authority.mode === 'full' ? 'trusted-host-authority' : 0,
+    limits };
+}
+
+/** Injectable dependencies allow real HTTP tests with disposable auth-owned keys. */
+export function createInvokeRouter({ auth = requireAuth, store = { loadKeys, keyHasScope },
+  execute = executeInvokeChild, audit,
+  cwd = process.cwd(), serverBrain = brainDir, registryBrain = globalBrainDir, limits = INVOKE_LIMITS,
+  commandScopes = composedCommandDirectories } = {}) {
+  const router = Router();
+  const resolveTargets = authority => authority.mode === 'restricted' ?
+    restrictedBrainTargets(authority, { serverBrain, registryBrain }) : new Map();
+  const recordAudit = audit || (event => appendVfsEvent(`invoke/${crypto.randomUUID()}`, event, {
+    vaultRoot: path.join(serverBrain, 'memory-vault'), workspaceId: 'invoke', actorRole: 'system', intent: 'Record developer invoke outcome',
+  }));
+  const active = new Map();
+  let total = 0;
+  router.get('/v1/invoke/capabilities', auth, (req, res) => {
+    try {
+      const authority = invokeAuthority(req, store);
+      res.json({ ok: true, operation: 'capabilities', result: capabilitiesFor(authority, limits, [...resolveTargets(authority).keys()]), error: null });
+    } catch (err) { fail(res, err.status || 503, 'capabilities', err.code || 'authority-unavailable', err.code ? err.message : 'Authority validation unavailable.'); }
+  });
+  router.post('/v1/invoke', auth, async (req, res) => {
+    const started = Date.now();
+    const { operation, params = {} } = req.body || {};
+    if (typeof operation !== 'string' || !operation) return fail(res, 400, null, 'missing-operation', 'Body must include { operation, params }.');
+    if (!Object.hasOwn(OPERATIONS, operation)) return fail(res, 404, operation, 'unknown-operation', 'Unknown operation.');
+    const def = OPERATIONS[operation];
+    let authority, timer, controller, disconnected, counted = false, outcome = 'denied', target = null, mutationBrain, mutationResult;
+    try {
+      if (!params || typeof params !== 'object' || Array.isArray(params)) throw new InvokeError(400, 'invalid-params', 'params must be an object.');
+      if (Buffer.byteLength(JSON.stringify(params)) > 16384) throw new InvokeError(413, 'input-limit', 'Invoke parameters exceed 16 KiB.');
+      authority = invokeAuthority(req, store);
+      const targets = resolveTargets(authority), targetNames = [...targets.keys()];
+      authorizeInvoke(authority, operation, def.scope, params, targetNames);
+      target = authority.mode === 'restricted' ? (operation === 'capabilities' ? null : params.target ?? 'server') : absoluteTarget(params.target, cwd);
+      const selectedBrain = authority.mode === 'restricted' && target ? targets.get(target) : serverBrain;
+      if (authority.mode === 'restricted' && operation === 'ssss.write') {
+        const brain = selectedBrain;
+        if (mutatingBrains.has(brain)) throw new InvokeError(429, 'brain-write-busy', 'A confined write is already active for this brain.');
+        mutatingBrains.add(brain); mutationBrain = brain;
+      }
+      if (total >= limits.concurrency || (active.get(authority.id) || 0) >= limits.perKey) throw new InvokeError(429, 'concurrency-limit', 'Execution concurrency limit reached.');
+      total++; active.set(authority.id, (active.get(authority.id) || 0) + 1); counted = true;
+      try { await recordAudit({ caller: authority.id, mode: authority.mode, operation, target, outcome: 'authorized' }); }
+      catch { throw new InvokeError(503, 'audit-unavailable', 'Execution audit is unavailable; no work was started.'); }
+      controller = new AbortController();
+      disconnected = () => { if (!res.writableEnded) controller.abort(); };
+      req.once('aborted', disconnected); res.once('close', disconnected);
+      const revalidate = () => {
+        try {
+          const current = invokeAuthority(req, store);
+          if (current.mode !== authority.mode) throw new Error('mode changed');
+          const currentTargets = resolveTargets(current);
+          authorizeInvoke(current, operation, def.scope, params, [...currentTargets.keys()]);
+          if (current.mode === 'restricted' && target && currentTargets.get(target) !== selectedBrain) throw new Error('target changed');
+        } catch { controller.abort(); }
+      };
+      revalidate();
+      timer = setInterval(revalidate, 250); timer.unref?.();
+      const context = { authority, target, serverBrain, selectedBrain, signal: controller.signal, limits, commandScopes,
+        run: options => {
+          revalidate();
+          return execute({ ...options, signal: controller.signal, limits });
+        } };
+      let result;
+      if (operation === 'capabilities') result = capabilitiesFor(authority, limits, targetNames);
+      else result = await HANDLERS[operation](params, context);
+      if (operation === 'ssss.write' && authority.mode === 'restricted') mutationResult = result;
+      revalidate();
+      if (controller.signal.aborted) throw new InvokeError(403, 'authority-ended', 'Caller authority ended during execution.');
+      outcome = 'success';
+      await recordAudit({ caller: authority.id, mode: authority.mode, operation, target, outcome, latency_ms: Date.now() - started });
+      return res.json({ ok: true, operation, result, error: null, scope: def.scope, latency_ms: Date.now() - started });
+    } catch (err) {
+      outcome = err instanceof InvokeError ? err.code : 'operation-failed';
+      // Error strings from owner code can contain secrets. Only curated policy
+      // messages and explicitly requested full-mode command output are returned.
+      try { await recordAudit({ caller: authority?.id || req.auth?.id || 'unresolved', operation, target, outcome, latency_ms: Date.now() - started }); }
+      catch {
+        logger.error('invoke', 'Execution outcome audit unavailable', { operation, caller: authority?.id || 'unresolved' });
+        return fail(res, 503, operation, 'audit-unavailable', 'Execution audit could not be recorded.', mutationResult ? { result: mutationResult } : {});
+      }
+      return fail(res, err.status || 400, operation, outcome, err instanceof InvokeError ? err.message : 'Operation failed.',
+        { scope: def.scope, latency_ms: Date.now() - started, ...(err.result || mutationResult ? { result: err.result || mutationResult } : {}) });
+    } finally {
+      clearInterval(timer);
+      if (mutationBrain) mutatingBrains.delete(mutationBrain);
+      if (disconnected) { req.removeListener('aborted', disconnected); res.removeListener('close', disconnected); }
+      if (counted) { total--; const n = active.get(authority.id) - 1; if (n) active.set(authority.id, n); else active.delete(authority.id); }
+    }
+  });
+  return router;
+}
+
+export const invokeRouter = createInvokeRouter();
+
+/** The categories `total-recall remember` documents. Singular, and closed. */
+const MEMORY_CATEGORIES = new Set(['invariant', 'preference', 'correction', 'fact', 'concept', 'pattern', 'anti-pattern', 'decision', 'lore']);
+
+/** Static projection of the shared CLI execution scopes. */
+function composedCommands(context) {
+  return listSurfaceCommands(context.commandScopes(context.target));
+}
+
+async function runCliVerb({ verb, args = [], timeoutMs }, context) {
+  if (typeof verb !== 'string' || !verb.trim()) throw new InvokeError(400, 'invalid-verb', 'cli.run needs a registered verb.');
+  if (!Array.isArray(args) || args.some(a => typeof a !== 'string' || a.includes('\0'))) throw new InvokeError(400, 'invalid-args', 'args must be an array of strings.');
+  const parts = verb.trim().split(/\s+/);
+  const [command] = parts;
+  const catalog = buildPluginCatalog(context.target);
+  const plugin = catalog.plugins.find(p => p.namespace === command && p.callable && p.activation.enabled);
+  if (!Object.hasOwn(CLI_COMMANDS, command) && !plugin && !composedCommands(context).some(c => c.name === command)) {
+    throw new InvokeError(404, 'unregistered-command', 'Command is not registered in the authorized target.');
+  }
+  const env = invokeEnvironment(true);
+  env.TR_INVOKE_CONTEXT = JSON.stringify({ caller: context.authority.id, mode: 'full', target: context.target });
+  return requireSuccessfulRun(await context.run({ entry: path.join(root, 'bin/total-recall.mjs'),
+    args: [...parts, ...args], cwd: context.target, env, timeoutMs }));
+}
+
+const HANDLERS = {
+  async 'cli.run'(params, context) { return await runCliVerb(params, context); },
+
+  async 'ssss.read'({ query, category, limit = 5, timeoutMs }, context) {
+    if (typeof query !== 'string' || !query.trim() || query.startsWith('-')) throw new InvokeError(400, 'invalid-query', 'query must be nonempty text, not a CLI option.');
+    if (category !== undefined && (typeof category !== 'string' || !/^[a-z][a-z-]{0,63}$/.test(category))) throw new InvokeError(400, 'invalid-category', 'Invalid category.');
+    if (context.authority.mode === 'restricted') {
+      const brain = context.selectedBrain;
+      const run = requireSuccessfulRun(await context.run({ entry: path.join(root, 'src/server/invoke-read-child.mjs'),
+        cwd: root, env: invokeEnvironment(false), timeoutMs, nodeArgs: ['--max-old-space-size=128', '--permission',
+          `--allow-fs-read=${path.join(root, 'src')}`, `--allow-fs-read=${path.join(root, 'node_modules')}`,
+          `--allow-fs-read=${path.join(root, 'package.json')}`, `--allow-fs-read=${brain}`],
+        input: JSON.stringify({ brain, query, category, limit: Math.max(1, Math.min(20, Number(limit) || 5)) }) }));
+      try { return JSON.parse(run.stdout); } catch { throw new InvokeError(502, 'invalid-owner-output', 'Retrieval returned invalid output.'); }
+    }
+    // Retrieval belongs to the owning CLI. It searches metadata and indexed body
+    // text with ranking and session chunks; a substring scan here would return
+    // different, worse results than `recall` for the same question.
+    const k = Math.max(1, Math.min(20, Number(limit) || 5));
+    const args = ['--local', '--format', 'json', '-k', String(k), '--no-sessions'];
+    if (category) args.push('--category', String(category));
+    // The query is ONE argv element, passed through `args` so it is never
+    // re-split on whitespace.
+    const run = await runCliVerb({ verb: 'recall', args: [query, ...args], timeoutMs }, context);
+    if (run.exit_code !== 0) throw new Error(run.stderr?.trim() || 'recall failed');
+    // The CLI pretty-prints ONE JSON array across many lines, so it cannot be
+    // read line-by-line: a line-based reader finds only `[` and fails to parse,
+    // which surfaces as a successful call returning zero results. Slice from the
+    // first `[` to the last `]` to tolerate leading log lines.
+    const stdout = String(run.stdout || '');
+    const start = stdout.indexOf('[');
+    const end = stdout.lastIndexOf(']');
+    let parsed = null;
+    if (start !== -1 && end > start) {
+      try { parsed = JSON.parse(stdout.slice(start, end + 1)); } catch { /* unparseable */ }
+    }
+    if (!Array.isArray(parsed)) throw new InvokeError(502, 'invalid-owner-output', 'Recall did not return a valid result array.');
+    const nodes = parsed.map(n => ({
+      slug: n.slug, category: n.category, title: n.title,
+      status: n.status, score: n.score, snippet: String(n.body || n.content || '').slice(0, 240),
+    }));
+    return { count: nodes.length, nodes };
+  },
+
+  async 'ssss.write'(params, context) {
+    const { category, title, content, tags, scope, timeoutMs } = params;
+    if (context.authority.mode === 'restricted') {
+      const brain = context.selectedBrain;
+      const run = await context.run({ entry: path.join(root, 'src/server/invoke-write-child.mjs'),
+        cwd: root, env: invokeEnvironment(false), timeoutMs, nodeArgs: ['--max-old-space-size=128', '--permission',
+          `--allow-fs-read=${path.join(root, 'src')}`, `--allow-fs-read=${path.join(root, 'node_modules')}`,
+          `--allow-fs-read=${path.join(root, 'package.json')}`, `--allow-fs-read=${brain}`,
+          `--allow-fs-write=${path.join(brain, 'memory-vault')}`,
+          `--allow-fs-write=${path.join(brain, 'memory-vault', '*')}`,
+          `--allow-fs-write=${path.join(brain, 'memory-derived')}`,
+          `--allow-fs-write=${path.join(brain, 'memory-derived', '*')}`],
+        input: JSON.stringify({ brain, params: { ...params, target: 'server' }, caller: context.authority.id }) });
+      let result;
+      try { result = JSON.parse(run.stdout); } catch { /* interruption may precede output */ }
+      if (run.exit_code !== 0 || run.termination_reason || run.truncated) {
+        throw new InvokeError(run.termination_reason === 'timeout' ? 504 : run.termination_reason === 'authority-ended' ? 403 : 422,
+          run.termination_reason || 'mutation-failed', 'Fact creation did not complete; check committed/indexed status before retry.',
+          result || { committed: 'unknown', indexed: false });
+      }
+      if (!result?.committed || !result?.indexed) throw new InvokeError(502, 'invalid-owner-output', 'Mutation returned invalid output.', { committed: 'unknown', indexed: false });
+      return result;
+    }
+    if (!content || typeof content !== 'string') throw new Error('ssss.write needs content.');
+    // Canonical memory is written by its owning CLI, never reimplemented here.
+    // `remember` runs the validated write path and recompiles the derived
+    // surfaces; a hand-rolled vault write would bypass both and could leave the
+    // indexes stale while reporting success.
+    const cat = typeof category === 'string' && category.trim() ? category.trim() : 'fact';
+    // These are the categories `remember` documents. They are singular, and a
+    // node TYPE (`facts`) is not one of them — passing it produced a confusing
+    // failure from deep inside the write path.
+    if (!MEMORY_CATEGORIES.has(cat)) {
+      throw new Error(`Unknown memory category '${cat}'. Valid: ${[...MEMORY_CATEGORIES].join(', ')}.`);
+    }
+    const text = title ? `${title}\n\n${content}` : content;
+    const args = ['--tags', Array.isArray(tags) && tags.length ? tags.join(',') : 'invoke'];
+    if (scope === 'global') args.push('--global');
+    else args.push('--project');
+    // Same rule as ssss.read: the memory text is one argv element, never split.
+    const run = await runCliVerb({ verb: `remember ${cat}`, args: [text, ...args], timeoutMs }, context);
+    if (run.exit_code !== 0) throw new Error(run.stderr?.trim() || run.stdout?.trim() || 'remember failed');
+    const created = /vault:\s*(\S+)/.exec(run.stdout || '')?.[1] || null;
+    return { category: cat, path: created, exit_code: run.exit_code };
+  },
+
+  async 'composable.list'(_params, context) {
+    const catalog = buildPluginCatalog(context.target);
+    const commands = composedCommands(context).filter(c => !Object.hasOwn(CLI_COMMANDS, c.name) &&
+      !catalog.plugins.some(p => p.callable && p.activation.enabled && p.namespace === c.name));
+    return { count: commands.length, commands };
+  },
+
+  async 'composable.run'({ name, args = [], timeoutMs }, context) {
+    if (typeof name !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(name)) throw new InvokeError(400, 'invalid-name', 'composable.run needs a kebab-case command name.');
+    if (Object.hasOwn(CLI_COMMANDS, name) || !composedCommands(context).some(c => c.name === name)) throw new InvokeError(404, 'unregistered-command', 'Composed name is not executable in the authorized target.');
+    const catalog = buildPluginCatalog(context.target);
+    if (catalog.plugins.some(p => p.callable && p.activation.enabled && p.namespace === name)) throw new InvokeError(409, 'shadowed-command', 'A plugin shadows this composed name.');
+    return await runCliVerb({ verb: name, args, timeoutMs }, context);
+  },
+
+  async 'decision.run'(params, context) {
+    if (!params.questions || typeof params.questions !== 'object' || Array.isArray(params.questions)) {
+      throw new InvokeError(400, 'invalid-questions', 'decision.run needs a question object.');
+    }
+    return runDecision('decision.run', params, context);
+  },
+
+  async 'decision.predict'(params, context) {
+    return runDecision('decision.predict', params, context);
+  },
+};
+
+async function runDecision(operation, params, context) {
+  const requested = params.timeoutMs === undefined ? context.limits.timeoutMs : Number(params.timeoutMs);
+  if (!Number.isFinite(requested) || requested <= 0) throw new InvokeError(400, 'invalid-timeout', 'timeoutMs must be positive and finite.');
+  const timeoutMs = Math.min(requested, context.limits.timeoutMs);
+  const env = invokeEnvironment(true);
+  env.TR_INVOKE_CONTEXT = JSON.stringify({ caller: context.authority.id, mode: 'full', target: context.target });
+  const run = await context.run({ entry: path.join(root, 'src/server/invoke-decision-child.mjs'),
+    cwd: context.target, env, timeoutMs,
+    input: JSON.stringify({ operation, params, brain: context.serverBrain, timeoutMs }) });
+  // Provider/auth diagnostics may contain credentials. Unlike requested cli.run
+  // output, these pipes are never exposed, even on timeout or malformed output.
+  if (run.termination_reason || run.truncated) {
+    const code = run.termination_reason || 'output-limit';
+    throw new InvokeError(code === 'timeout' ? 504 : code === 'authority-ended' ? 403 : 422,
+      code, 'Decision execution did not complete; remote work may already have been accepted.');
+  }
+  let envelope;
+  try { envelope = JSON.parse(run.stdout); } catch { /* denied below */ }
+  if (run.exit_code !== 0) throw new InvokeError(502, 'decision-failed', 'Decision owner failed.');
+  if (envelope?.ok === false) {
+    const credential = envelope.error === 'credential-unavailable';
+    throw new InvokeError(credential ? 503 : 502, credential ? 'credential-unavailable' : 'provider-failed',
+      credential ? 'Decision credential is unavailable.' : 'Decision provider failed.');
+  }
+  if (envelope?.ok !== true || !envelope.result || typeof envelope.result !== 'object' || Array.isArray(envelope.result)) {
+    throw new InvokeError(502, 'invalid-owner-output', 'Decision owner returned invalid output.');
+  }
+  return envelope.result;
+}

package/src/server/routes/plugins.mjs

@@ -323,7 +323,7 @@ router.post("/api/plugins/:id/run", requireAuth, requireScope("config:write"), a
 
     if (execution) {
       if (stdin !== undefined) return badRequest(res, 'Credential operations require direct local execution');
-      if (!pluginActivation(plugin).enabled && !['on', 'off', 'status', 'health', 'jobs', '--help', 'help'].includes(subcommand)) return badRequest(res, `Plugin ${plugin.id} is inactive`);
+      if (!pluginActivation(plugin, { projectRoot: projectRoot() }).enabled && !['on', 'off', 'status', 'health', 'jobs', '--help', 'help'].includes(subcommand)) return badRequest(res, `Plugin ${plugin.id} is inactive`);
       const { loadPluginModule } = await import('../../core/plugin-runtime.mjs');
       const owner = await loadPluginModule('cli-agents', 'command-executor', { activeRequired: true });
       const result = await owner.executeCommand({ plugin, subcommand, args, execution, projectRoot: projectRoot() });

package/scaffold/.agent/skills/plugins/SKILL.md

@@ -1,57 +0,0 @@
----
-name: plugins
-description: Create, scaffold, design, test and distribute Total Recall plugins that load correctly and render a functional, uniquely designed card. Use when an agent builds, changes or reviews a tr-plugin-*.
-repo_scoped: false
----
-
-# Total Recall plugins
-
-Run `total-recall plugin --help` first. A plugin is a standalone repository (`tr-plugin-<id>`) with a `plugin.json`, a CLI handler, tests, and optionally a live panel. Core Total Recall holds portable memory and generic loading; every capability lives in a plugin.
-
-## Decide how the plugin will be used
-
-1. **Brick in a project (default for apps).** `total-recall plugin vendor <id | git-url | path> [dir]` copies the source into `bricks/<id>` and records it in `tr-bricks.json`. The project owns the copy and ships with no runtime dependency on the plugin or Total Recall. Plugins exist so nobody starts from zero.
-2. **Direct use.** `total-recall plugin install <source>` then `total-recall <id> ...` for your own machines and workflow.
-3. **New project.** Prefer adding bricks to starting from an empty folder. Run `total-recall plugin bricks` to see what a project already has.
-
-Declare how yours is distributed: `distribution: { "tier": "core|official|personal|community", "license": "open|closed" }`. Closed means an operated service behind a thin client; see [distribution](references/distribution.md). Never rely on a local license check for protection.
-
-## Build order
-
-1. `total-recall plugin create <id> --name "<neutral name>" --description "<one concrete sentence>" --with-cli`.
-2. Write the CLI first. Every subcommand prints JSON with `--json` and returns a non-zero exit on failure. Required subcommands where relevant: `status --json`, `config get|set --json`, `secrets status --json`. Details: [manifest contract](references/manifest-contract.md).
-3. Declare every command in `plugin.json` with typed arguments and an effect (`read`, `write`, `destructive`, `send`). The card builds its forms from these, so an undeclared command is invisible to users and agents.
-4. Declare `configuration.fields` for every setting and `secrets[]` for every credential. Credentials go through `total-recall auth secret`, never ambient environment variables, argv, files or logs.
-5. Design the card: pick a template and widgets that fit the function, set brand tokens, write `ui/DESIGN.md`. Details: [card design](references/card-design.md).
-6. Test (see below), then run the validator: `total-recall plugin info <id>` must report no errors.
-
-## Rules that make a plugin compatible
-
-- **Real data only.** A value appears on the card only if a command or the host returned it. Never hard-code metrics such as "ONLINE" or sample numbers. If a source fails, show the failure and the time of the last attempt.
-- **Functional first.** The card must show what the plugin can do (all declared commands), all of its settings, all of its credentials, and its real status. Decoration comes after, never instead.
-- **Unique design per plugin.** Layout and brand follow the plugin's function. Two plugins with different jobs must not look alike. No decorative animation, no emoji as icons, no skins that imitate hardware.
-- **Neutral, descriptive name.** No invented brand. The name says what the plugin does.
-- **Tokens only.** No hard-coded colors in plugin UI code; use the brand tokens and the design tokens in `ui/DESIGN.md`.
-- **Accessible and touch ready.** Controls are at least 44 px, keyboard reachable, with visible focus, contrast-checked state colors, and reduced motion respected.
-- **Secrets stay secret.** Set from the card over stdin for declared secret arguments only. Show present or missing, never the value.
-- **State through the vault contracts.** No unmanaged raw file writes for records; use SSSS operations.
-- **Fail closed.** Missing credentials, failed providers and unavailable peers produce explicit errors, never a success badge.
-- **Copy.** No filler words, and no sentence ends with a preposition.
-
-## Test before you share
-
-- Unit tests for each subcommand, including failure paths and `--json` shape.
-- A manifest test that loads `plugin.json` with the validator and checks that every `card_layout` source command and every `status.command` is a declared subcommand.
-- A secrets test proving no secret value appears in argv, stdout, logs or the card state.
-- Run suites in the background on the configured test node and read the real exit status. A passing health probe is not a test result.
-
-## Distribution
-
-- Open plugins are vendorable and can be shared with `plugin share`. Closed service-backed plugins list price and usage in the manifest `monetization` block. See [distribution](references/distribution.md).
-- Third parties publish with the same manifest and conformance tests. The store lists signed, immutable versions and never runs plugin code.
-
-## References
-
-- [Manifest contract](references/manifest-contract.md): every field, with a complete example.
-- [Card design](references/card-design.md): templates, widgets, brand tokens, the design process, anti-patterns.
-- [Distribution](references/distribution.md): bricks, tiers, license class, monetization, store, third-party authoring.

package/scaffold/.agent/skills/plugins/references/card-design.md

@@ -1,55 +0,0 @@
-# Card design
-
-The host runs one engine for behavior: actions with typed forms, settings, credentials, status, activity. You choose the design: a layout template, the widgets inside it, and brand tokens. Every plugin gets its own look, tied to what it does.
-
-## Pick a template by function
-| Template | Use it when the job is | Arrangement |
-| --- | --- | --- |
-| `console` | running a task and reading the result | primary form beside the output |
-| `ledger` | reviewing records and acting on one | table first, action rail at the side |
-| `monitor` | watching live health | gauges or status tiles above a live log |
-| `inbox` | working through items | list and detail |
-| `dashboard` | an overview then a few actions | status tiles, then actions |
-| `workbench` | several related tools | tabs, one tool per tab |
-| `vault` | managing stored records | record list with per-row actions |
-
-## Widgets
-`status`, `actions`, `table`, `detail`, `log`, `form`, `keypad`, `gauge`, `list`, `settings`, `credentials`, `activity`, `live`. Widgets that read data (`table`, `detail`, `list`, `gauge`, `log`) need `source: { "command": "<declared read command>", "path": "<json path>" }`. `table` needs `columns` with `key`, `label` and optional `format` (`text number money date datetime bytes percent status`). `form` needs `command`. `actions` may list `commands` to feature; the rest stay reachable under "All commands". `live` mounts the plugin's own sandboxed panel.
-
-```json
-"card_layout": { "template": "ledger", "regions": [
-  { "widget": "status", "variant": "strip" },
-  { "widget": "table", "source": { "command": "list", "path": "payments" },
-    "columns": [ { "key": "id", "label": "Payment" }, { "key": "amount", "label": "Amount", "format": "money" }, { "key": "state", "label": "State", "format": "status" } ] },
-  { "widget": "actions", "commands": ["refund"] },
-  { "widget": "settings" }, { "widget": "credentials" } ] }
-```
-Always include `settings` and `credentials` (or let the engine append them) so every setting and credential is visible.
-
-## Name, logo and brand
-- **A wrapper of someone else's API keeps that provider's brand.** Name it for the provider (`Stripe`, `Google Maps`, `Telnyx Voice`) and set `branding.provider`. Do not invent a brand for a wrapper.
-- **First-party plugins** use a plain descriptive name.
-- **Monetized, operated services** (you run the instance or hold the provider accounts) have their own brand and logo, distinct from the software and providers behind them. Credit the underlying software in the about text.
-- **Real logos only.** `branding.logo` is an `.svg` or `.png` shipped in the plugin. A provider's logo comes from the provider's brand kit and is used only to identify the integration; record its source in `ui/LOGO.md`. First-party and monetized plugins ship an original mark. Never use an emoji or a generic icon as the brand. `branding.icon` is deprecated and warns.
-
-## Drawer
-The card face stays compact: logo, real status, and the two or three primary actions. The host's slide-out drawer carries Settings, Credentials, Usage and Projects (see [distribution](distribution.md)); declare `configuration`, `secrets` and a `status` command and the drawer fills itself. Do not build your own settings or usage screens.
-
-## Brand tokens
-```json
-"branding": { "color": "#635bff", "accent": "#0a2540", "font": "ibm-plex",
-  "density": "compact", "radius": "sm", "header": "ledger-rule" }
-```
-- `color`, `accent`: `#rrggbb`. The engine derives surfaces and state colors and checks contrast.
-- `font`: `system inter ibm-plex space-grotesk jetbrains-mono dm-sans outfit fraunces newsreader chivo-mono`.
-- `density`: `compact comfortable spacious`. `radius`: `none sm md lg pill`. `header`: `plain ledger-rule band tab-strip badge-left`.
-Choose tokens from the plugin's function and audience, not from a default: a payments ledger reads as compact and exact, a messaging inbox as roomy and conversational, a security monitor as high-contrast and dense.
-
-## Design process for an agent
-1. Write down in `ui/DESIGN.md`: who uses the card, the two or three actions they take most, what they need to see without clicking, and the reasons for the template and tokens.
-2. Declare `card_layout` and `branding`. Bind every data widget to a real command.
-3. Render at 360, 768 and 1280 px wide and look at it. Check light and dark, keyboard focus order, 44 px targets and long values (wrapping, truncation with a title, empty and error states).
-4. Compare against other plugins' cards. If it looks like another plugin's, change the template, widget order or tokens.
-
-## Anti-patterns the validator or review rejects
-Fixed metrics; sample data; a made-up brand on a wrapper; an emoji or generic icon in place of a logo; decorative canvas or CSS animation; emoji as icons; hardware-skin imitations; raw hex colors in plugin code; one template used for every plugin; hiding settings or credentials; showing a secret value; claiming "connected" without a returned status.

package/scaffold/.agent/skills/plugins/references/distribution.md

@@ -1,23 +0,0 @@
-# Distribution, monetization and third-party plugins
-
-## Open plugins as bricks
-`total-recall plugin vendor <source> [dir]` copies a plugin into `bricks/<id>` and records version, source and content hash in `tr-bricks.json`. `total-recall plugin bricks` reports each brick as unchanged, modified or missing. Edits are expected; the project owns the copy. Install the dependencies the command prints and add the brick's tests to the project gates. Do not edit the plugin repository to satisfy one project.
-
-## Tiers and license class
-- `core`: ships with Total Recall (memory, auth, mesh, project tooling).
-- `official`: published by the maintainer, installed on demand.
-- `personal`: one owner's own variant; keep operator-specific names and infrastructure here.
-- `community`: published by a third party.
-Open plugins carry their source. Closed plugins are services.
-
-## Monetizable (closed) plugins
-Source that runs on a user's machine cannot be protected by a local license check. A closed plugin is a thin client plus a hosted service that holds provider accounts, meters usage, enforces plan and credits, and bills. The client reads the license key from `total-recall auth secret`, sends signed requests, and reports a clear error when the license is missing, lapsed or out of credit. Show price and usage on the card. Typical candidates are wrappers over third-party APIs such as telephony, messaging, domains and mail, and metered AI access.
-
-## Installations and usage
-Adding a plugin to a project records the installation locally: plugin, version, content hash, project path, date. The host lists these in the drawer's Projects tab with status (unchanged, modified, missing). Each brick appends usage entries to `<project>/.tr/usage/<plugin>.jsonl`: time, command, exit state, duration, units and cost for metered calls, never payloads or secrets. Closed services meter on the server with one key per project. Nothing is sent anywhere unless the owner explicitly opts in. A brick's `usage` helper must not write request or response bodies.
-
-## Third-party authoring
-Anyone can build a plugin with `plugin create`, the manifest contract and the conformance checks, then submit it to the store. The store lists signed, immutable, hash-pinned versions, pays out to the manifest `monetization.recipient`, and never executes plugin code. API wrappers can be generated from an OpenAPI document with `plugin from-openapi` once it ships; the output is open and follows this contract.
-
-## Status of these features
-Implemented: `plugin vendor`, `plugin bricks`, the manifest validator for arguments, effects, status, layout, branding and distribution. In progress under the plugin-split project: the shared card engine, the slide-out drawer, installation and usage ledgers, logo rendering and templates, the host `stdin` channel for secrets, `new`, `plugin test`, `plugin from-openapi`, license verification and the store. Declare the contract fields now; they validate today and render as the engine lands.

package/scaffold/.agent/skills/plugins/references/manifest-contract.md

@@ -1,90 +0,0 @@
-# Manifest contract
-
-`plugin.json` is validated by Total Recall (`total-recall plugin info <id>` shows errors and warnings). Fields marked optional change what the card can show; omitting them still yields a card that lists commands and secrets.
-
-## Identity and distribution
-```json
-{
-  "id": "payments",
-  "name": "Payments",
-  "version": "0.1.0",
-  "description": "One concrete sentence about the job this plugin performs.",
-  "license": "MIT",
-  "use_cases": ["commerce"],
-  "distribution": { "tier": "official", "license": "open" }
-}
-```
-`id` is lowercase kebab-case. `name` is neutral and descriptive. `tier` is `core`, `official`, `personal` or `community`. `license` is `open` (source can be vendored) or `closed` (operated service).
-
-## Commands
-```json
-"cli": {
-  "command": "payments",
-  "handler": "./cli.mjs",
-  "subcommands": [
-    { "name": "status", "description": "Connection and credential state", "effect": "read", "output": "json" },
-    { "name": "refund", "description": "Refund a payment", "effect": "destructive", "output": "json", "timeout_ms": 30000,
-      "args": [
-        { "name": "paymentId", "flag": "--payment", "label": "Payment", "type": "string", "required": true },
-        { "name": "reason", "flag": "--reason", "label": "Reason", "type": "choice", "options": ["duplicate", "fraud", "requested"] },
-        { "name": "amount", "flag": "--amount", "label": "Amount", "type": "number", "description": "Leave empty for a full refund" }
-      ] },
-    { "name": "token-set", "description": "Store the API key", "effect": "write",
-      "args": [{ "name": "value", "label": "API key", "type": "string", "secret": true, "positional": true, "required": true }] }
-  ]
-}
-```
-- **Argument types:** `string`, `number`, `boolean`, `choice` (requires `options`). Each needs `name` (camelCase), `label`, and either `flag` (`--kebab-case`) or `positional: true`.
-- **Effects:** `read` (default), `write`, `destructive`, `send`. The card asks for confirmation before `destructive` and `send`, and never auto-runs anything but `read`.
-- **Secret arguments** are read from stdin by the CLI, never from a flag. A secret argument must not declare a `flag`.
-- Duplicate command or argument names are rejected.
-
-## Status
-```json
-"status": { "command": "status", "refresh_seconds": 30 }
-```
-The command must be declared and must be a `read` command. It prints:
-```json
-{ "ok": true, "summary": "Connected, live mode", "items": [
-  { "label": "Account", "value": "acct_123", "state": "ok" },
-  { "label": "Webhook secret", "value": "missing", "state": "warn" } ] }
-```
-States are `ok`, `warn`, `error`, `unknown`. Do not use `card_face.metrics`: fixed text cannot reflect state, and the validator warns about it.
-
-Only an explicit `effect: "read"` permits execution from a card. Missing effects default to reference-only; names such as `config`, `list` or `check` do not establish that a command is read-only. Grouped commands that accept a write action must not be labeled read.
-
-## Secret input through the owner interface
-
-Declare exactly one argument with `type: "string"`, `secret: true` and no `flag`. A secret does not require positional metadata. The isolated owner interface can call `host.run('save-key', [], { stdin: value })`. The host authenticates and checks write scope, the server validates the manifest declaration and the 65,536-byte UTF-8 limit, and the child receives the value through stdin with `--stdin`. Empty, undeclared and ambiguous secret input is rejected. Child stdout/stderr is suppressed for this operation, and the owner interface receives only success or failure. Re-read nonsecret credential status through a separate command; never echo the submitted value.
-
-## Workspaces
-
-`workspace.component` identifies an owner-supplied `ui.elements` id or tag. The host mounts that interface through the same isolated panel boundary; core contains no plugin-specific workspace implementation. `workspace.permissions` may list `microphone`, `camera` or `notifications`, but a declaration does not grant device access. Device-backed workspaces remain explicitly unavailable until a safe host capability bridge exists. Never add `allow-same-origin` to the scripts-only iframe to bypass this limitation.
-
-## Settings and credentials
-```json
-"configuration": { "fields": [
-  { "name": "mode", "type": "string", "label": "Mode", "options": ["test", "live"], "default": "test", "required": true },
-  { "name": "currency", "type": "string", "label": "Default currency", "default": "usd" },
-  { "name": "sendReceipts", "type": "boolean", "label": "Email receipts", "default": true } ] },
-"secrets": [
-  { "key": "PAYMENTS_SECRET_KEY", "description": "Secret key for payment processing", "required": true },
-  { "key": "PAYMENTS_WEBHOOK_SECRET", "description": "Signs incoming webhooks", "required": false } ]
-```
-Field names are camelCase and may not contain password, secret, apiKey or token; those belong in `secrets` with uppercase keys. Declare every setting and credential the plugin really reads, so the card shows all of them.
-
-## Layout and branding
-See [card design](card-design.md) for `card_layout` and `branding`. Branding also carries the real logo and, for wrappers, the provider:
-```json
-"branding": { "logo": "ui/logo.svg", "provider": { "name": "Stripe", "url": "https://stripe.com" }, "color": "#635bff" }
-```
-
-## Monetization (optional)
-```json
-"monetization": { "model": "metered", "price_cents": 2, "currency": "usd", "period": "per-use",
-  "license_key_secret": "PAYMENTS_LICENSE_KEY", "checkout_url": "https://example.com/plugins/payments" }
-```
-Models: `free`, `one-time`, `subscription`, `metered`, `take-rate` (with `take_rate_basis_points`). Enforcement belongs to the operated service; see [distribution](distribution.md).
-
-## Runtime, tasks and UI elements
-`tasks` run a declared subcommand on a cron schedule; each needs `intent`, `schedule`, `command`. `ui.elements` lists the optional live panel (`kind: "panel"` or `"card-face"`, `tag`, `module`). A plugin does not need `ui` at all for the standard card.

package/scaffold/.agent/skills/plugins/references/optimized/index.md

@@ -1,9 +0,0 @@
-# Task references
-
-Read only sections needed for the operation, including their prerequisites and constraints. Commands and plain paths assume the skill root. This index selects documentation, not permission or rule applicability.
-
-- [Overview](section-01.md)
-- [Where to work](section-02.md)
-- [Implement a capability](section-03.md)
-- [Validate the actual job](section-04.md)
-- [Share with another user](section-05.md)

package/scaffold/.agent/skills/plugins/references/optimized/manifest.json

@@ -1,35 +0,0 @@
-{
-  "version": 1,
-  "source_sha256": "d5470c2686d2e6d8aeb35977acad1bbd46a3018759b9753843e78005f2a9edf0",
-  "entrypoint_sha256": "3d5ec8c164079c3f17b197bdeeef1dc2a49f27e5e1de8d53e6148627fb0dd6d5",
-  "sections": [
-    {
-      "path": "references/optimized/section-01.md",
-      "sha256": "6fd88392d0552c027241b6b3494ca17dc00aa7029d4bf061de199d4a31f04124"
-    },
-    {
-      "path": "references/optimized/section-02.md",
-      "sha256": "d5651cfeeddb7c12545acc96771e85c486069161c111a4576e4af34b089a6c8e"
-    },
-    {
-      "path": "references/optimized/section-03.md",
-      "sha256": "325c0da34e876b557a215c7b43d486f9447434af0c6188678eed347a21be4d79"
-    },
-    {
-      "path": "references/optimized/section-04.md",
-      "sha256": "b6ff62769477d9e88b703feaa88bef37ba2314b2a3de96d87778e21b25e94dd3"
-    },
-    {
-      "path": "references/optimized/section-05.md",
-      "sha256": "34681996b33ab68fdd479cfadec9e9ddf059fc511a81a5fa6778adaca78ab815"
-    },
-    {
-      "path": "references/optimized/index.md",
-      "sha256": "410f8b54e7645ee566baea54d62ea05d9869e5bd0566652bb69e42a0138d075a"
-    },
-    {
-      "path": "references/optimized/original.md",
-      "sha256": "d5470c2686d2e6d8aeb35977acad1bbd46a3018759b9753843e78005f2a9edf0"
-    }
-  ]
-}