total-recall-brain 3.40.0 → 3.40.2

package/scaffold/.agent/skills/total-recall/plugins/composable-cli/ui/card.js

@@ -0,0 +1,273 @@
+/**
+ * Pipeline Composer — Dynamic Command Orchestration Engine
+ * Bespoke Animated Web Component Card Face with Live Flow Pipeline Visualizer.
+ *
+ * Zero emojis, authentic commercial brand identity, touch-first ergonomics (>=44px).
+ */
+
+export class PipelineComposerCard extends HTMLElement {
+  constructor() {
+    super();
+    this.status = 'Ready';
+    this.executing = false;
+  }
+
+  connectedCallback() {
+    this.attachShadow({ mode: 'open' });
+    this.render();
+    this.initPipelineAnimation();
+  }
+
+  async execute(action, args = []) {
+    const out = this.shadowRoot.querySelector('#card-out');
+    const badge = this.shadowRoot.querySelector('#status-badge');
+    if (out) out.textContent = `[PIPELINE ROUTER] Invoking ${action.toUpperCase()}...`;
+    if (badge) badge.textContent = 'ROUTING';
+    this.executing = true;
+
+    try {
+      const res = await this.host?.run(action, args);
+      let text = '';
+      if (typeof res === 'object') {
+        text = res.output || JSON.stringify(res, null, 2);
+      } else {
+        text = String(res || 'Execution completed without output.');
+      }
+      if (out) out.textContent = text.trim();
+      if (badge) badge.textContent = 'ONLINE';
+    } catch (err) {
+      if (out) out.textContent = `[PIPELINE FAULT] ${err.message}`;
+      if (badge) badge.textContent = 'ERROR';
+    } finally {
+      this.executing = false;
+    }
+  }
+
+  initPipelineAnimation() {
+    const canvas = this.shadowRoot.querySelector('#flow-canvas');
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+
+    let progress = 0;
+    const nodes = [
+      { x: 30, y: 32, label: 'INPUT' },
+      { x: 110, y: 32, label: 'TRANSFORM' },
+      { x: 210, y: 32, label: 'FILTER' },
+      { x: 300, y: 32, label: 'SINK' }
+    ];
+
+    const draw = () => {
+      if (!this.isConnected) return;
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+      // Draw connection lines
+      ctx.strokeStyle = 'rgba(99, 102, 241, 0.25)';
+      ctx.lineWidth = 2;
+      ctx.beginPath();
+      ctx.moveTo(nodes[0].x, nodes[0].y);
+      for (let i = 1; i < nodes.length; i++) {
+        ctx.lineTo(nodes[i].x, nodes[i].y);
+      }
+      ctx.stroke();
+
+      // Draw packet pulse
+      const totalLen = nodes[nodes.length - 1].x - nodes[0].x;
+      const packetX = nodes[0].x + (progress % 1) * totalLen;
+      ctx.fillStyle = this.executing ? '#38bdf8' : '#818cf8';
+      ctx.shadowColor = ctx.fillStyle;
+      ctx.shadowBlur = 8;
+      ctx.beginPath();
+      ctx.arc(packetX, 32, 4, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.shadowBlur = 0;
+
+      // Draw stage nodes
+      for (const node of nodes) {
+        ctx.fillStyle = '#0f172a';
+        ctx.strokeStyle = '#6366f1';
+        ctx.lineWidth = 1.5;
+        ctx.beginPath();
+        ctx.arc(node.x, node.y, 8, 0, Math.PI * 2);
+        ctx.fill();
+        ctx.stroke();
+
+        ctx.fillStyle = '#c7d2fe';
+        ctx.font = '8px monospace';
+        ctx.textAlign = 'center';
+        ctx.fillText(node.label, node.x, node.y + 18);
+      }
+
+      progress += this.executing ? 0.03 : 0.008;
+      requestAnimationFrame(draw);
+    };
+
+    requestAnimationFrame(draw);
+  }
+
+  render() {
+    this.shadowRoot.innerHTML = `
+      <style>
+        :host {
+          display: block;
+          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+          background: #0b0f19;
+          color: #e0e7ff;
+          border-radius: 8px;
+          border: 1px solid rgba(99, 102, 241, 0.35);
+          box-shadow: 0 10px 28px rgba(0, 0, 0, 0.45);
+          padding: 18px;
+          box-sizing: border-box;
+          overflow: hidden;
+        }
+        .header {
+          display: flex;
+          justify-content: space-between;
+          align-items: flex-start;
+          margin-bottom: 14px;
+        }
+        .brand-meta {
+          display: flex;
+          flex-direction: column;
+          gap: 2px;
+        }
+        .title {
+          font-size: 16px;
+          font-weight: 700;
+          letter-spacing: 0.04em;
+          text-transform: uppercase;
+          color: #c7d2fe;
+          margin: 0;
+        }
+        .subtitle {
+          font-size: 11px;
+          color: #94a3b8;
+          letter-spacing: 0.02em;
+          margin: 0;
+        }
+        .badge {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          font-size: 10px;
+          font-weight: 700;
+          letter-spacing: 0.08em;
+          text-transform: uppercase;
+          color: #818cf8;
+          background: rgba(99, 102, 241, 0.12);
+          border: 1px solid rgba(99, 102, 241, 0.3);
+          border-radius: 4px;
+          padding: 4px 8px;
+        }
+        .visual-display {
+          position: relative;
+          background: #030712;
+          border: 1px solid rgba(99, 102, 241, 0.2);
+          border-radius: 6px;
+          margin-bottom: 14px;
+          overflow: hidden;
+        }
+        canvas {
+          display: block;
+          width: 100%;
+          height: 64px;
+        }
+        .telemetry-row {
+          display: flex;
+          justify-content: space-between;
+          padding: 6px 10px;
+          background: rgba(255, 255, 255, 0.03);
+          border-top: 1px solid rgba(99, 102, 241, 0.15);
+          font-family: monospace;
+          font-size: 11px;
+          color: #cbd5e1;
+        }
+        .actions-grid {
+          display: grid;
+          grid-template-columns: repeat(3, 1fr);
+          gap: 8px;
+          margin-bottom: 12px;
+        }
+        .touch-btn {
+          min-height: 44px;
+          min-width: 44px;
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          background: rgba(99, 102, 241, 0.08);
+          border: 1px solid rgba(99, 102, 241, 0.25);
+          color: #c7d2fe;
+          font-size: 11px;
+          font-weight: 600;
+          letter-spacing: 0.04em;
+          text-transform: uppercase;
+          border-radius: 6px;
+          cursor: pointer;
+          transition: background 0.15s ease, border-color 0.15s ease;
+          padding: 6px 8px;
+          text-align: center;
+        }
+        .touch-btn:hover {
+          background: rgba(99, 102, 241, 0.18);
+          border-color: rgba(99, 102, 241, 0.5);
+        }
+        .touch-btn:active {
+          transform: translateY(1px);
+        }
+        .output-box {
+          background: #020617;
+          border: 1px solid rgba(99, 102, 241, 0.2);
+          border-radius: 6px;
+          padding: 8px 10px;
+          font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+          font-size: 11px;
+          line-height: 1.45;
+          color: #94a3b8;
+          min-height: 48px;
+          max-height: 85px;
+          overflow-y: auto;
+          white-space: pre-wrap;
+          word-break: break-word;
+        }
+      </style>
+
+      <div class="header">
+        <div class="brand-meta">
+          <h2 class="title">Pipeline Composer</h2>
+          <p class="subtitle">Dynamic Command Orchestration Engine</p>
+        </div>
+        <div id="status-badge" class="badge">READY</div>
+      </div>
+
+      <div class="visual-display">
+        <canvas id="flow-canvas" width="340" height="64"></canvas>
+        <div class="telemetry-row">
+          <span>Execution: Direct</span>
+          <span>Risk Gate: Fail-Closed</span>
+        </div>
+      </div>
+
+      <div class="actions-grid">
+        <button id="btn-list" class="touch-btn" type="button">Catalog</button>
+        <button id="btn-inspect" class="touch-btn" type="button">Inspect</button>
+        <button id="btn-history" class="touch-btn" type="button">History</button>
+      </div>
+
+      <div id="card-out" class="output-box">Dynamic command registry operational. Ready for pipeline invocation.</div>
+    `;
+
+    this.shadowRoot.querySelector('#btn-list')?.addEventListener('click', () => {
+      this.execute('list');
+    });
+    this.shadowRoot.querySelector('#btn-inspect')?.addEventListener('click', () => {
+      this.execute('read', ['startup-check']);
+    });
+    this.shadowRoot.querySelector('#btn-history')?.addEventListener('click', () => {
+      this.execute('history');
+    });
+  }
+}
+
+if (!customElements.get('tr-composable-cli-card')) {
+  customElements.define('tr-composable-cli-card', PipelineComposerCard);
+}

package/scaffold/.agent/skills/total-recall/plugins/embeddings/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plugin authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/scaffold/.agent/skills/total-recall/plugins/embeddings/README.md

@@ -0,0 +1,20 @@
+# Embeddings
+
+> Local embedding model management: provider/model status, benchmark, index build and coverage
+
+## Sharing
+
+Offer it to your other Total Recall nodes over the mesh:
+
+```bash
+npx total-recall plugin share embeddings
+```
+
+Peers install it with `npx total-recall plugin install peer:<this-node>/embeddings`.
+
+## Features
+
+- **Identifier**: `embeddings`
+- **Version**: 0.1.0
+- **Use cases**: operations, ai
+- **CLI Command**: `npx total-recall embeddings`

package/scaffold/.agent/skills/total-recall/plugins/embeddings/cli.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * Embeddings CLI Handler
+ * Executed via: npx total-recall embeddings <subcommand>
+ *
+ * Owns local embedding provider discovery and index coverage for a brain:
+ * which provider/model actually serves vectors, whether that model is local
+ * (no text leaves the machine, no provider spend), and how much of the vault
+ * is embedded. Building the index itself stays with `total-recall compile`,
+ * which owns the embeddings.db lifecycle.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const PLUGIN_ID = 'embeddings';
+const PLUGIN_DIR = path.dirname(new URL(import.meta.url).pathname);
+const PLUGIN_VERSION = JSON.parse(fs.readFileSync(path.join(PLUGIN_DIR, 'plugin.json'), 'utf8')).version;
+const DEFAULT_URL = 'http://127.0.0.1:11434';
+const HOSTED_PROVIDERS = ['OPENROUTER_API_KEY', 'GOOGLE_API_KEY', 'OPENAI_API_KEY'];
+
+/** The brain this invocation targets: project brain when present, else global. */
+function resolveVault() {
+  const candidates = [
+    path.join(process.cwd(), '.agent', 'skills', 'total-recall'),
+    path.join(process.env.HOME || '', '.agent', 'skills', 'total-recall'),
+  ];
+  for (const dir of candidates) {
+    if (dir && fs.existsSync(path.join(dir, 'memory-vault'))) return dir;
+  }
+  return null;
+}
+
+function ollamaUrl() {
+  const raw = process.env.TR_OLLAMA_URL || process.env.OLLAMA_HOST || DEFAULT_URL;
+  const withScheme = /^https?:\/\//i.test(raw) ? raw : `http://${raw}`;
+  try {
+    const u = new URL(withScheme);
+    if (!u.port) u.port = '11434';
+    return u.origin;
+  } catch { return DEFAULT_URL; }
+}
+
+async function probe(url, timeoutMs = 4000) {
+  try {
+    const res = await fetch(`${url}/api/tags`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return { reachable: false, reason: `HTTP ${res.status}` };
+    const data = await res.json();
+    return { reachable: true, models: (data.models || []).map(m => m.name) };
+  } catch (err) {
+    return { reachable: false, reason: err.message };
+  }
+}
+
+/** Pick the embedding-capable model with the vault's vector width, as the core does. */
+async function selectModel(url, dims = 768) {
+  const tags = await probe(url);
+  if (!tags.reachable) return null;
+  for (const name of tags.models || []) {
+    try {
+      const res = await fetch(`${url}/api/show`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model: name }), signal: AbortSignal.timeout(5000),
+      });
+      if (!res.ok) continue;
+      const info = await res.json();
+      const caps = info.capabilities || [];
+      // Older servers do not report capabilities; fall back to a name hint.
+      const capable = caps.includes('embedding') || /embed/i.test(name);
+      if (!capable) continue;
+      const width = Object.entries(info.model_info || {})
+        .filter(([k]) => k.endsWith('.embedding_length')).map(([, v]) => v)[0];
+      if (width && width !== dims) continue;
+      return { name, width: width || null };
+    } catch { /* try the next model */ }
+  }
+  return null;
+}
+
+/** Coverage of the vault against its embeddings index, read without loading it all. */
+function coverage(brainDir) {
+  const dbPath = path.join(brainDir, 'memory-derived', 'embeddings.db');
+  // No vault_nodes here: counting nodes is vaultNodeCount's job, and a
+  // placeholder key would clobber a real count when this object is spread.
+  const result = { embedded: null, model: null, db_bytes: null, percent: null };
+  if (fs.existsSync(dbPath)) result.db_bytes = fs.statSync(dbPath).size;
+  if (!fs.existsSync(dbPath)) return result;
+  const py = spawnSync('python3', ['-c', `
+import sqlite3, json, sys
+try:
+    c = sqlite3.connect(${JSON.stringify(dbPath)})
+    n = c.execute('select count(*) from vault_embeddings').fetchone()[0]
+    models = [r[0] for r in c.execute('select model, count(*) from vault_embeddings group by model order by count(*) desc')]
+    print(json.dumps({'embedded': n, 'models': models}))
+except Exception as e:
+    print(json.dumps({'error': str(e)}))
+`], { encoding: 'utf8', timeout: 20000 });
+  try {
+    const parsed = JSON.parse(py.stdout || '{}');
+    result.embedded = parsed.embedded ?? null;
+    result.model = parsed.models?.[0] ?? null;
+  } catch { /* leave nulls */ }
+  return result;
+}
+
+function vaultNodeCount(brainDir) {
+  const vault = path.join(brainDir, 'memory-vault');
+  let count = 0;
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.md')) count++;
+    }
+  };
+  try { walk(vault); } catch { return null; }
+  return count;
+}
+
+const IMPLEMENTED = {};
+
+IMPLEMENTED.status = async (args) => {
+  const json = args.includes('--json');
+  const url = ollamaUrl();
+  const probed = await probe(url);
+  const model = probed.reachable ? await selectModel(url) : null;
+  const brain = resolveVault();
+  const report = {
+    plugin: PLUGIN_ID,
+    configured_url: url,
+    ollama: { reachable: probed.reachable, models: probed.models || [], reason: probed.reason || null },
+    selected_model: model?.name ?? null,
+    embedding_dims: model?.width ?? null,
+    local: Boolean(model),
+    // A hosted fallback is what the core uses when no local model answers.
+    hosted_fallback_keys: HOSTED_PROVIDERS.filter(k => Boolean(process.env[k])),
+    brain: brain ? {
+      dir: brain,
+      // Spread coverage FIRST: it returns its own vault_nodes placeholder which
+      // would otherwise clobber the counted value placed after it.
+      ...coverage(brain),
+      vault_nodes: vaultNodeCount(brain),
+    } : null,
+  };
+  if (report.brain && report.brain.vault_nodes && report.brain.embedded != null) {
+    report.brain.percent = Math.round((report.brain.embedded / report.brain.vault_nodes) * 100);
+  }
+  if (json) { console.log(JSON.stringify(report, null, 1)); return; }
+  console.log(`Embeddings v${PLUGIN_VERSION}`);
+  console.log(`  endpoint:   ${url} ${probed.reachable ? '(reachable)' : `(unreachable: ${probed.reason})`}`);
+  console.log(`  model:      ${model ? `${model.name}${model.width ? ` (${model.width} dims)` : ''}` : 'none — would fall back to a hosted provider'}`);
+  console.log(`  local:      ${model ? 'yes — vectors never leave this machine' : 'NO — text would be sent to a provider'}`);
+  if (!model && report.hosted_fallback_keys.length) console.log(`  fallback:   ${report.hosted_fallback_keys.join(', ')}`);
+  if (report.brain) {
+    const b = report.brain;
+    console.log(`  brain:      ${b.dir}`);
+    console.log(`  vault:      ${b.vault_nodes} nodes`);
+    console.log(`  embedded:   ${b.embedded ?? 'no index'}${b.model ? ` (model: ${b.model})` : ''}${b.percent != null ? ` — ${b.percent}%` : ''}`);
+  }
+};
+
+IMPLEMENTED.models = async (args) => {
+  const json = args.includes('--json');
+  const url = ollamaUrl();
+  const probed = await probe(url);
+  if (!probed.reachable) {
+    if (json) console.log(JSON.stringify({ url, reachable: false, reason: probed.reason, models: [] }));
+    else console.error(`Embeddings: ${url} is unreachable (${probed.reason}).`);
+    process.exitCode = 1;
+    return;
+  }
+  const rows = [];
+  for (const name of probed.models || []) {
+    let width = null, capable = false;
+    try {
+      const res = await fetch(`${url}/api/show`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model: name }), signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) {
+        const info = await res.json();
+        capable = (info.capabilities || []).includes('embedding') || /embed/i.test(name);
+        width = Object.entries(info.model_info || {}).filter(([k]) => k.endsWith('.embedding_length')).map(([, v]) => v)[0] ?? null;
+      }
+    } catch { /* report what is known */ }
+    rows.push({ name, embedding_capable: capable, dims: width });
+  }
+  if (json) { console.log(JSON.stringify({ url, reachable: true, models: rows }, null, 1)); return; }
+  console.log(`Embeddings v${PLUGIN_VERSION} — ${url}`);
+  for (const r of rows) console.log(`  ${r.embedding_capable ? '●' : '○'} ${r.name}${r.dims ? ` (${r.dims} dims)` : ''}`);
+  if (!rows.some(r => r.embedding_capable)) console.log('  no embedding-capable model — run: embeddings pull');
+};
+
+IMPLEMENTED.pull = async (args) => {
+  const model = args.find(a => !a.startsWith('-')) || 'nomic-embed-text';
+  const json = args.includes('--json');
+  const url = ollamaUrl();
+  if (!json) console.log(`Embeddings: pulling ${model} from ${url} ...`);
+  const res = spawnSync('ollama', ['pull', model], {
+    encoding: 'utf8', timeout: 600000,
+    env: { ...process.env, OLLAMA_HOST: url.replace(/^https?:\/\//, '') },
+  });
+  const ok = res.status === 0;
+  if (json) { console.log(JSON.stringify({ model, ok, status: res.status, stderr: ok ? null : (res.stderr || '').slice(-400) })); if (!ok) process.exitCode = 1; return; }
+  if (!ok) { console.error(`  failed: ${(res.stderr || res.stdout || '').trim().slice(-300)}`); process.exitCode = 1; return; }
+  console.log(`  ✅ ${model} ready`);
+};
+
+IMPLEMENTED.benchmark = async (args) => {
+  const json = args.includes('--json');
+  const countIdx = args.indexOf('--count');
+  const samples = Number(countIdx > -1 ? args[countIdx + 1] : 0) || 10;
+  const url = ollamaUrl();
+  const model = await selectModel(url);
+  if (!model) {
+    if (json) console.log(JSON.stringify({ ok: false, reason: 'no embedding-capable model available', url }));
+    else console.error(`Embeddings: no embedding-capable model at ${url}. Run: embeddings pull`);
+    process.exitCode = 1;
+    return;
+  }
+  const text = 'Contact High Life Smoke Shop, 2485 Corporate Pkwy Burlington NC 27215, phone 336-828-7106, status active.';
+  const timings = [];
+  for (let i = 0; i < samples; i++) {
+    const t0 = Date.now();
+    try {
+      const res = await fetch(`${url}/api/embeddings`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model: model.name, prompt: text }), signal: AbortSignal.timeout(60000),
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      await res.json();
+      timings.push(Date.now() - t0);
+    } catch (err) {
+      if (json) console.log(JSON.stringify({ ok: false, reason: err.message, url, model: model.name }));
+      else console.error(`Embeddings: benchmark failed: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const total = timings.reduce((a, b) => a + b, 0);
+  const avg = total / timings.length;
+  const brain = resolveVault();
+  const nodes = brain ? vaultNodeCount(brain) : null;
+  const report = {
+    ok: true, url, model: model.name, samples,
+    ms_per_embedding: Math.round(avg),
+    min_ms: Math.min(...timings), max_ms: Math.max(...timings),
+    vault_nodes: nodes,
+    projected_minutes: nodes ? Math.round((avg * nodes) / 60000) : null,
+  };
+  if (json) { console.log(JSON.stringify(report, null, 1)); return; }
+  console.log(`Embeddings v${PLUGIN_VERSION} — benchmark (${samples} samples, ${model.name})`);
+  console.log(`  ${Math.round(avg)} ms/embedding  (min ${Math.min(...timings)}, max ${Math.max(...timings)})`);
+  if (nodes) console.log(`  ${nodes} vault nodes → about ${report.projected_minutes} minutes to embed fully`);
+};
+
+IMPLEMENTED.coverage = async (args) => {
+  const json = args.includes('--json');
+  const brain = resolveVault();
+  if (!brain) {
+    if (json) console.log(JSON.stringify({ ok: false, reason: 'no brain found in the current directory or home' }));
+    else console.error('Embeddings: no brain found. Run from a project with .agent/skills/total-recall, or after total-recall init.');
+    process.exitCode = 1;
+    return;
+  }
+  const nodes = vaultNodeCount(brain);
+  const cov = coverage(brain);
+  const report = { ok: true, brain, vault_nodes: nodes, embedded: cov.embedded, model: cov.model, db_bytes: cov.db_bytes,
+    percent: (nodes && cov.embedded != null) ? Math.round((cov.embedded / nodes) * 100) : null };
+  if (json) { console.log(JSON.stringify(report, null, 1)); return; }
+  console.log(`Embeddings v${PLUGIN_VERSION} — coverage`);
+  console.log(`  brain:    ${brain}`);
+  console.log(`  vault:    ${nodes} nodes`);
+  console.log(`  embedded: ${cov.embedded ?? 'no index'}${cov.model ? ` (model: ${cov.model})` : ''}${report.percent != null ? ` — ${report.percent}%` : ''}`);
+  if (report.percent != null && report.percent < 100) console.log('  run: total-recall compile   (builds the missing vectors)');
+};
+
+export async function run(argv = []) {
+  const args = Array.isArray(argv) ? argv.slice(3) : [];
+  const sub = args[0] || 'status';
+  const json = args.includes('--json');
+  const wantsHelp = args.includes('--help') || args.includes('-h');
+
+  if (wantsHelp || sub === 'help') {
+    const subs = [...new Set(['status', ...Object.keys(IMPLEMENTED)])];
+    console.log(`Embeddings v${PLUGIN_VERSION}
+
+Usage: total-recall embeddings <subcommand> [options]
+
+Subcommands:
+${subs.map((s) => `  ${s}`).join('\n')}
+
+Options:
+  --json      Machine-readable output
+  --help, -h  Show this help
+
+Environment:
+  TR_OLLAMA_URL / OLLAMA_HOST   Ollama endpoint (default http://127.0.0.1:11434)
+                                When unset, the core falls back to a hosted
+                                provider and vault text leaves the machine.`);
+    return;
+  }
+
+  if (IMPLEMENTED[sub]) return IMPLEMENTED[sub](args.slice(1));
+
+  console.error(`Embeddings: "${sub}" is not implemented. Run 'total-recall embeddings --help' for available subcommands.`);
+  process.exitCode = 2;
+}
+export default run;