total-recall-brain 3.44.0 → 3.46.0

package/scaffold/.agent/skills/total-recall/plugins/embeddings/ui/home.js

@@ -0,0 +1,353 @@
+/**
+ * Embeddings Home — the plugin's native page.
+ *
+ * Answers, from the plugin's own JSON operations: which provider serves
+ * vectors and whether text leaves this machine, how much of the vault has a
+ * usable vector, which models the endpoint offers, and how fast the selected
+ * model embeds. Reads `status` and `models` on open; benchmark and pull run
+ * only when the operator asks. Anything not reported renders as a dash.
+ */
+
+const DASH = '—';
+const BENCHMARK_MAX = 20;
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, c => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[c]));
+}
+
+/** A reported value, or a dash when the operation did not report one. */
+function shown(value) {
+  return value === null || value === undefined || value === '' ? DASH : escapeHtml(value);
+}
+
+function formatBytes(n) {
+  if (!Number.isFinite(n)) return DASH;
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 ** 2) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 ** 3) return `${(n / 1024 ** 2).toFixed(1)} MB`;
+  return `${(n / 1024 ** 3).toFixed(2)} GB`;
+}
+
+/** host.run may hand back parsed JSON, raw stdout, or a { stdout } envelope. */
+export function parseResult(res) {
+  if (res && typeof res === 'object' && typeof res.stdout === 'string') return parseResult(res.stdout);
+  if (res && typeof res === 'object') return res;
+  if (typeof res === 'string' && res.trim().startsWith('{')) return JSON.parse(res);
+  throw new Error('the operation returned no JSON');
+}
+
+const LOCALITY = {
+  local: { tone: 'ok', label: 'Local', note: 'Text sent for embedding stays on this machine.' },
+  remote: { tone: 'warn', label: 'Remote', note: 'The endpoint or the selected model runs on another machine, so vault text leaves this host.' },
+  unknown: { tone: 'warn', label: 'Unknown', note: 'No local model qualifies. Total Recall may try a hosted provider, which would send vault text off this machine.' },
+  disabled: { tone: 'muted', label: 'Disabled', note: 'Embeddings are turned off for this brain.' },
+};
+
+export class EmbeddingsHome extends HTMLElement {
+  constructor() {
+    super();
+    this.status = { phase: 'loading' };
+    this.models = { phase: 'loading' };
+    this.bench = { phase: 'idle' };
+    this.pull = { phase: 'idle' };
+    this.count = 10;
+    this.pullModel = '';
+  }
+
+  connectedCallback() {
+    if (!this.shadowRoot) this.attachShadow({ mode: 'open' });
+    this.render();
+    this.load();
+  }
+
+  async read(op, args) {
+    try {
+      return { phase: 'ready', data: parseResult(await this.host.run(op, args)) };
+    } catch (err) {
+      return { phase: 'unavailable', error: err?.message || String(err) };
+    }
+  }
+
+  async load() {
+    if (!this.host) {
+      const error = 'No Total Recall host is connected, so the plugin operations cannot run.';
+      this.status = { phase: 'unavailable', error };
+      this.models = { phase: 'unavailable', error };
+      this.render();
+      return;
+    }
+    this.status = { phase: 'loading' };
+    this.models = { phase: 'loading' };
+    this.render();
+    [this.status, this.models] = await Promise.all([
+      this.read('status', ['--json']),
+      this.read('models', ['--json']),
+    ]);
+    this.render();
+  }
+
+  /** Runs a user-triggered operation; a JSON body with ok:false is a failure. */
+  async act(slot, op, args) {
+    if (!this.host || this[slot].phase === 'running') return;
+    this[slot] = { phase: 'running' };
+    this.render();
+    const result = await this.read(op, args);
+    if (result.phase !== 'ready') this[slot] = { phase: 'failed', error: result.error };
+    else if (result.data.ok === false) this[slot] = { phase: 'failed', error: result.data.reason || 'the operation reported a failure', data: result.data };
+    else this[slot] = { phase: 'done', data: result.data };
+    this.render();
+  }
+
+  runBenchmark() {
+    const n = Number(this.count);
+    if (!Number.isInteger(n) || n < 1 || n > BENCHMARK_MAX) {
+      this.bench = { phase: 'failed', error: `Samples must be a whole number from 1 to ${BENCHMARK_MAX}.` };
+      this.render();
+      return;
+    }
+    this.act('bench', 'benchmark', ['--count', String(n), '--json']);
+  }
+
+  async runPull() {
+    const model = this.pullModel.trim();
+    if (!model) {
+      this.pull = { phase: 'failed', error: 'Type the exact model name to pull.' };
+      this.render();
+      return;
+    }
+    await this.act('pull', 'pull', [model, '--json']);
+    if (this.pull.phase === 'done') this.load();
+  }
+
+  renderProvider() {
+    const s = this.status;
+    if (s.phase === 'loading') return `<p class="notice" data-design-component="notice">Reading provider status${DASH}</p>`;
+    if (s.phase !== 'ready') return `<p class="notice bad" data-design-component="notice">Provider status unavailable: ${escapeHtml(s.error)}</p>`;
+    const d = s.data;
+    const loc = LOCALITY[d.locality] || { tone: 'warn', label: d.locality || 'Unreported', note: '' };
+    const attempts = Array.isArray(d.attempts) ? d.attempts : [];
+    return `
+      <div class="verdict">
+        <span class="chip ${loc.tone}" data-design-component="locality-chip">${escapeHtml(loc.label)}</span>
+        <span class="note">${escapeHtml(loc.note)}</span>
+      </div>
+      <dl class="facts">
+        <div><dt>Provider</dt><dd>${shown(d.provider)}</dd></div>
+        <div><dt>Endpoint</dt><dd class="mono">${shown(d.endpoint)}</dd></div>
+        <div><dt>Selected model</dt><dd class="mono">${shown(d.selected_model)}</dd></div>
+        <div><dt>Vector width</dt><dd class="mono">${d.embedding_dims ? `${escapeHtml(d.embedding_dims)} dims` : DASH}</dd></div>
+      </dl>
+      ${d.reason ? `<p class="notice" data-design-component="notice">${escapeHtml(d.reason)}</p>` : ''}
+      ${attempts.length ? `
+        <ul class="attempts">
+          ${attempts.map(a => `
+            <li class="mono ${a.reachable ? 'ok' : 'bad'}">${escapeHtml(a.url)} ${DASH} ${a.reachable ? 'reachable' : `unreachable: ${shown(a.reason)}`}</li>`).join('')}
+        </ul>` : ''}`;
+  }
+
+  renderCredentials() {
+    const fallback = this.status.phase === 'ready' ? this.status.data.hosted_fallback : null;
+    return `
+      <dl class="facts">
+        <div><dt>Hosted fallback</dt><dd class="mono">${shown(fallback)}</dd></div>
+        <div><dt>Credential owner</dt><dd>Auth</dd></div>
+      </dl>
+      <p class="notice" data-design-component="notice">Keys for hosted embedding providers are held by the Auth owner. This plugin does not read, list or display them, so their readiness is reported as unknown rather than guessed.</p>`;
+  }
+
+  renderCoverage() {
+    const s = this.status;
+    if (s.phase === 'loading') return `<p class="notice" data-design-component="notice">Counting vectors${DASH}</p>`;
+    if (s.phase !== 'ready') return `<p class="notice bad" data-design-component="notice">Coverage unavailable: ${escapeHtml(s.error)}</p>`;
+    const b = s.data.brain;
+    if (!b) return '<p class="notice" data-design-component="notice">No brain was found in the working directory or home, so there is no vault to measure.</p>';
+    if (b.state !== 'ok') {
+      return `
+        <p class="notice warn" data-design-component="notice">Index state <span class="mono">${shown(b.state)}</span>: ${shown(b.reason)}</p>
+        <dl class="facts">
+          <div><dt>Brain</dt><dd class="mono">${shown(b.dir)}</dd></div>
+          <div><dt>Vault nodes</dt><dd class="mono">${shown(b.vault_nodes)}</dd></div>
+          <div><dt>Missing a vector</dt><dd class="mono">${shown(b.missing)}</dd></div>
+        </dl>`;
+    }
+    const counts = [
+      ['Usable', b.embedded, 'ok'],
+      ['Stale', b.stale, b.stale ? 'warn' : ''],
+      ['Wrong width', b.mismatched, b.mismatched ? 'warn' : ''],
+      ['Missing', b.missing, b.missing ? 'warn' : ''],
+      ['Orphaned rows', b.orphaned, ''],
+    ];
+    return `
+      <div class="coverage">
+        <div class="figure" data-design-component="coverage-figure">${b.percent === null || b.percent === undefined ? DASH : `${escapeHtml(b.percent)}%`}</div>
+        <div class="figure-caption">${shown(b.embedded)} of ${shown(b.vault_nodes)} vault nodes have a current, correct-width vector</div>
+      </div>
+      <ul class="counts">
+        ${counts.map(([label, value, tone]) => `
+          <li class="count-row ${tone}" data-design-component="count-row"><span>${label}</span><span class="mono">${shown(value)}</span></li>`).join('')}
+      </ul>
+      <dl class="facts">
+        <div><dt>Indexed by</dt><dd class="mono">${shown(b.model)}</dd></div>
+        <div><dt>Index rows</dt><dd class="mono">${shown(b.rows)}</dd></div>
+        <div><dt>Index size</dt><dd class="mono">${formatBytes(b.db_bytes)}</dd></div>
+        <div><dt>Unparseable files</dt><dd class="mono">${shown(b.parse_errors)}</dd></div>
+        <div><dt>Brain</dt><dd class="mono">${shown(b.dir)}</dd></div>
+      </dl>
+      ${b.stale || b.mismatched || b.missing ? '<p class="notice" data-design-component="notice">Rebuild the unusable vectors with <span class="mono">total-recall compile</span>.</p>' : ''}`;
+  }
+
+  renderModels() {
+    const m = this.models;
+    if (m.phase === 'loading') return `<p class="notice" data-design-component="notice">Listing models${DASH}</p>`;
+    if (m.phase !== 'ready') return `<p class="notice bad" data-design-component="notice">Model list unavailable: ${escapeHtml(m.error)}</p>`;
+    const d = m.data;
+    if (d.reachable === false) return '<p class="notice bad" data-design-component="notice">No endpoint answered. The endpoints tried are listed under Provider.</p>';
+    const rows = Array.isArray(d.models) ? d.models : [];
+    if (!rows.length) return `<p class="notice" data-design-component="notice">${shown(d.url)} reports no models. Pull one below.</p>`;
+    return `
+      <p class="caption">${shown(d.url)} ${DASH} the vault needs ${shown(d.vault_dims)}-dim vectors</p>
+      <ul class="models">
+        ${rows.map(r => `
+          <li class="model-row${r.name === d.selected ? ' selected' : ''}" data-design-component="model-row">
+            <span class="mono name">${shown(r.name)}${r.name === d.selected ? ' <span class="tag ok">selected</span>' : ''}</span>
+            <span class="tags">
+              <span class="tag">${r.dims ? `${escapeHtml(r.dims)} dims` : 'width unknown'}</span>
+              <span class="tag ${r.embedding_capable ? 'ok' : ''}">${r.embedding_capable ? 'embeds' : 'no embedding'}</span>
+              <span class="tag ${r.compatible ? 'ok' : 'warn'}">${r.compatible ? 'vault-compatible' : 'not usable'}</span>
+              ${r.upstream ? '<span class="tag warn">upstream</span>' : ''}
+            </span>
+          </li>`).join('')}
+      </ul>`;
+  }
+
+  renderBenchmark() {
+    const b = this.bench;
+    const running = b.phase === 'running';
+    const d = b.data || {};
+    return `
+      <div class="action">
+        <label class="field">Samples
+          <input id="bench-count" type="number" min="1" max="${BENCHMARK_MAX}" step="1" value="${escapeHtml(this.count)}" ${running ? 'disabled' : ''}>
+        </label>
+        <button id="bench-run" type="button" class="primary" data-design-component="button-primary" ${running || !this.host ? 'disabled' : ''}>${running ? 'Measuring' : 'Run benchmark'}</button>
+      </div>
+      <p class="caption">Embeds a neutral sentence with the selected model, never vault text. Runs only against a local model.</p>
+      ${b.phase === 'failed' ? `<p class="notice bad" data-design-component="notice">Benchmark failed: ${escapeHtml(b.error)}</p>` : ''}
+      ${b.phase === 'done' ? `
+        <dl class="facts">
+          <div><dt>Per embedding</dt><dd class="mono">${shown(d.ms_per_embedding)} ms</dd></div>
+          <div><dt>Range</dt><dd class="mono">${shown(d.min_ms)}${DASH}${shown(d.max_ms)} ms</dd></div>
+          <div><dt>Samples</dt><dd class="mono">${shown(d.samples)} × ${shown(d.dims)} dims</dd></div>
+          <div><dt>Full vault</dt><dd class="mono">${d.projected_minutes === null || d.projected_minutes === undefined ? DASH : `about ${escapeHtml(d.projected_minutes)} min for ${shown(d.vault_nodes)} nodes`}</dd></div>
+          <div><dt>Measured</dt><dd class="mono">${shown(d.model)} on ${shown(d.url)}</dd></div>
+        </dl>` : ''}`;
+  }
+
+  renderPull() {
+    const p = this.pull;
+    const running = p.phase === 'running';
+    const d = p.data || {};
+    return `
+      <div class="action">
+        <label class="field grow">Model name
+          <input id="pull-model" type="text" spellcheck="false" autocomplete="off" value="${escapeHtml(this.pullModel)}" ${running ? 'disabled' : ''}>
+        </label>
+        <button id="pull-run" type="button" class="primary" data-design-component="button-primary" ${running || !this.host ? 'disabled' : ''}>${running ? 'Pulling' : 'Pull model'}</button>
+      </div>
+      <p class="caption">Downloads the named model to the configured loopback endpoint. Cloud and upstream models are refused. A pull can take several minutes.</p>
+      ${p.phase === 'failed' ? `<p class="notice bad" data-design-component="notice">Pull failed${d.model ? ` for <span class="mono">${escapeHtml(d.model)}</span>` : ''}: ${escapeHtml(p.error)}</p>` : ''}
+      ${p.phase === 'done' ? `<p class="notice ok" data-design-component="notice"><span class="mono">${shown(d.model)}</span> is ready on <span class="mono">${shown(d.url)}</span>.</p>` : ''}`;
+  }
+
+  render() {
+    const root = this.shadowRoot;
+    if (!root) return;
+    const loading = this.status.phase === 'loading' || this.models.phase === 'loading';
+    root.innerHTML = `
+      <style>
+        :host {
+          display: block;
+          box-sizing: border-box;
+          padding: var(--spacing-lg, 16px);
+          color: var(--colors-text, #ecfeff);
+          background: var(--colors-background, #07171d);
+          font-family: var(--typography-body-font-family, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif);
+          font-size: var(--typography-body-font-size, 13px);
+        }
+        *, *::before, *::after { box-sizing: border-box; }
+        @media (prefers-reduced-motion: reduce) {
+          *, *::before, *::after { transition-duration: 0.01ms !important; animation-duration: 0.01ms !important; }
+        }
+        header { display: flex; align-items: center; justify-content: space-between; gap: var(--spacing-md, 12px); flex-wrap: wrap; margin-bottom: var(--spacing-lg, 16px); }
+        h1 { margin: 0; font-size: 18px; }
+        h1 + p { margin: 2px 0 0; color: var(--colors-muted, #67e8f9); font-size: var(--typography-label-font-size, 11px); }
+        h2 { margin: 0 0 var(--spacing-md, 12px); font-size: var(--typography-label-font-size, 11px); font-weight: var(--typography-label-font-weight, 700); letter-spacing: 0.05em; text-transform: uppercase; color: var(--colors-muted, #67e8f9); }
+        .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: var(--spacing-md, 12px); }
+        section { background: var(--colors-surface, #0e2a35); border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-md, 6px); padding: var(--spacing-md, 12px); min-width: 0; }
+        .mono { font-family: var(--typography-mono-font-family, 'JetBrains Mono', 'Fira Code', monospace); font-size: var(--typography-mono-font-size, 12px); overflow-wrap: anywhere; }
+        .verdict { display: flex; align-items: center; gap: var(--spacing-sm, 8px); flex-wrap: wrap; margin-bottom: var(--spacing-md, 12px); }
+        .chip { font-size: var(--typography-label-font-size, 11px); font-weight: 700; text-transform: uppercase; padding: var(--spacing-xs, 4px) var(--spacing-sm, 8px); border-radius: var(--rounded-md, 6px); border: 1px solid currentColor; }
+        .note, .caption { color: var(--colors-muted, #67e8f9); font-size: var(--typography-label-font-size, 11px); }
+        .caption { margin: 0 0 var(--spacing-sm, 8px); }
+        .ok { color: var(--colors-ok, #10b981); }
+        .warn { color: var(--colors-warn, #f59e0b); }
+        .bad { color: var(--colors-danger, #ef4444); }
+        .muted { color: var(--colors-muted, #67e8f9); }
+        .facts { display: grid; gap: var(--spacing-xs, 4px); margin: 0; }
+        .facts div { display: flex; justify-content: space-between; gap: var(--spacing-md, 12px); }
+        dt { color: var(--colors-muted, #67e8f9); }
+        dd { margin: 0; text-align: right; }
+        .notice { margin: var(--spacing-sm, 8px) 0 0; padding: var(--spacing-sm, 8px); background: var(--colors-background, #07171d); border-radius: var(--rounded-sm, 4px); }
+        .attempts, .counts, .models { list-style: none; margin: var(--spacing-sm, 8px) 0 0; padding: 0; display: grid; gap: var(--spacing-xs, 4px); }
+        .coverage { display: flex; align-items: baseline; gap: var(--spacing-md, 12px); flex-wrap: wrap; margin-bottom: var(--spacing-sm, 8px); }
+        .figure { font-family: var(--typography-figure-font-family, 'JetBrains Mono', monospace); font-size: var(--typography-figure-font-size, 28px); font-weight: var(--typography-figure-font-weight, 800); }
+        .figure-caption { color: var(--colors-muted, #67e8f9); }
+        .count-row { display: flex; justify-content: space-between; font-family: var(--typography-mono-font-family, 'JetBrains Mono', monospace); font-size: var(--typography-mono-font-size, 12px); }
+        .count-row:not(.ok):not(.warn) { color: var(--colors-muted, #67e8f9); }
+        .counts { margin-bottom: var(--spacing-md, 12px); }
+        .model-row { display: flex; justify-content: space-between; align-items: center; gap: var(--spacing-sm, 8px); flex-wrap: wrap; background: var(--colors-background, #07171d); border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-sm, 4px); padding: var(--spacing-sm, 8px); }
+        .model-row.selected { border-color: var(--colors-primary, #06b6d4); }
+        .tags { display: flex; gap: var(--spacing-xs, 4px); flex-wrap: wrap; }
+        .tag { font-size: 10px; padding: 2px 6px; border-radius: var(--rounded-sm, 4px); border: 1px solid var(--colors-line, #164e63); color: var(--colors-muted, #67e8f9); }
+        .tag.ok { color: var(--colors-ok, #10b981); }
+        .tag.warn { color: var(--colors-warn, #f59e0b); }
+        .action { display: flex; align-items: flex-end; gap: var(--spacing-sm, 8px); flex-wrap: wrap; margin-bottom: var(--spacing-sm, 8px); }
+        .field { display: grid; gap: var(--spacing-xs, 4px); color: var(--colors-muted, #67e8f9); font-size: var(--typography-label-font-size, 11px); }
+        .field.grow { flex: 1 1 180px; }
+        input { min-height: 44px; padding: 0 var(--spacing-sm, 8px); color: var(--colors-text, #ecfeff); background: var(--colors-background, #07171d); border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-sm, 4px); font-family: var(--typography-mono-font-family, 'JetBrains Mono', monospace); }
+        input[type=number] { width: 88px; }
+        button.primary { min-height: 44px; padding: 0 var(--spacing-lg, 16px); border: 0; border-radius: var(--rounded-sm, 4px); cursor: pointer; font-weight: 700; color: var(--colors-on-primary, #07171d); background: var(--colors-primary, #06b6d4); transition: background 0.15s ease; }
+        button.primary:hover:not(:disabled) { background: var(--colors-primary-hover, #22d3ee); }
+        button:disabled { opacity: 0.6; cursor: not-allowed; }
+        button.refresh { min-height: 44px; padding: 0 var(--spacing-md, 12px); color: var(--colors-text, #ecfeff); background: transparent; border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-sm, 4px); cursor: pointer; }
+        button:focus-visible, input:focus-visible { outline: 2px solid var(--colors-primary-hover, #22d3ee); outline-offset: 2px; }
+      </style>
+      <header>
+        <div>
+          <h1>Embeddings</h1>
+          <p>Vectors behind Total Recall search for this brain</p>
+        </div>
+        <button id="refresh" type="button" class="refresh" ${loading || !this.host ? 'disabled' : ''}>${loading ? 'Reading' : 'Refresh'}</button>
+      </header>
+      <div class="grid">
+        <section data-design-component="section" aria-labelledby="h-provider"><h2 id="h-provider">Provider</h2>${this.renderProvider()}</section>
+        <section data-design-component="section" aria-labelledby="h-coverage"><h2 id="h-coverage">Vault coverage</h2>${this.renderCoverage()}</section>
+        <section data-design-component="section" aria-labelledby="h-models"><h2 id="h-models">Models on the endpoint</h2>${this.renderModels()}</section>
+        <section data-design-component="section" aria-labelledby="h-credentials"><h2 id="h-credentials">Credentials</h2>${this.renderCredentials()}</section>
+        <section data-design-component="section" aria-labelledby="h-benchmark"><h2 id="h-benchmark">Benchmark</h2>${this.renderBenchmark()}</section>
+        <section data-design-component="section" aria-labelledby="h-pull"><h2 id="h-pull">Pull a model</h2>${this.renderPull()}</section>
+      </div>`;
+
+    root.getElementById('refresh')?.addEventListener('click', () => this.load());
+    root.getElementById('bench-count')?.addEventListener('input', e => { this.count = e.target.value; });
+    root.getElementById('bench-run')?.addEventListener('click', () => this.runBenchmark());
+    root.getElementById('pull-model')?.addEventListener('input', e => { this.pullModel = e.target.value; });
+    root.getElementById('pull-run')?.addEventListener('click', () => this.runPull());
+  }
+}
+
+if (!customElements.get('tr-embeddings-home')) {
+  customElements.define('tr-embeddings-home', EmbeddingsHome);
+}

package/scaffold/.agent/skills/total-recall/plugins/git/DESIGN.md

@@ -0,0 +1,31 @@
+---
+name: Git Copper Ledger
+description: A copper and paper ledger for repository state and linked worktrees.
+colors:
+  background: "#fcf7ef"
+  surface: "#f5e9d9"
+  text: "#32241b"
+  border: "#b29176"
+  accent: "#85411c"
+  muted: "#684b38"
+  danger: "#9c2924"
+typography:
+  body:
+    fontFamily: "system-ui, sans-serif"
+  heading:
+    fontFamily: "Georgia, serif"
+  mono:
+    fontFamily: "ui-monospace, monospace"
+spacing:
+  md: 16px
+rounded:
+  md: 6px
+---
+
+# Git Copper Ledger
+
+Use a warm paper background, a serif title, and tabular monospace counts. The repository audit reads first. Present conflicts and unpushed commits beside separate staged, unstaged, and untracked counts. Reserve copper for navigation and focus, and use red with a written label for failures.
+
+Below the audit, list the registered worktrees like ledger entries. Give each entry its own branch or commit, path, and state. Wrap long paths and stack the form and metrics at narrow widths. Use an inset confirmation with the exact target for worktree changes.
+
+Treat a missing measurement as unknown. Label ahead and behind as local upstream comparisons. Announce read and action results in text, preserve a visible keyboard focus outline, and keep controls at least 44 pixels tall.

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

@@ -0,0 +1,136 @@
+# Git
+
+The whole git CLI through Total Recall. Every git command works: anything that is not a plugin
+operation runs git itself, with your arguments, git's hooks, output and exit status. On top of git,
+the plugin signs git in from the auth store, checks commits and pushes, takes a snapshot before
+destructive commands, and records the intent behind each change.
+
+```bash
+total-recall git status
+total-recall git pull --rebase
+total-recall git help rebase        # git's own help for a command
+total-recall git --help             # the plugin's operations
+total-recall git commit --help      # one plugin operation's help (-h is git's usage)
+```
+
+The native Home opens with an audit and registered worktrees. It reads diff statistics on request and confirms the exact destination or target before a worktree change. Its [design](DESIGN.md) and SSSS blocks under `ui/chunks/` ship with the plugin.
+
+## Install
+
+```bash
+npx total-recall plugin install git
+```
+
+## Commit and push
+
+- `commit [git commit arguments]` refuses a missing or machine-derived identity, unresolved
+  conflicts and a detached HEAD, then runs git's own `commit` with your arguments unchanged.
+- Before `commit` and `push`, guards run:
+  - **Secret firewall:** the staged content and outgoing commits are compared with fingerprints of
+    every value in the auth store. A match refuses the command and names the key, never the value.
+  - **Rules:** workflow files (`.github/workflows`), internal project records in public
+    repositories, and machine-derived identities are refused.
+  - **Force-push guard:** `--force` becomes `--force-with-lease`. Deleting a remote branch needs
+    `--reason <text>`, which is recorded.
+
+## Undo
+
+Before a destructive command (`reset --hard`, `checkout -- <paths>`, `restore`, `clean`,
+`branch -D`, `stash drop|clear`, `rebase`, `filter-branch`, `update-ref -d`) the plugin records a
+snapshot of refs, the index and files.
+
+```bash
+total-recall git undo --list
+total-recall git undo <event>
+```
+
+## Sign-in
+
+```bash
+total-recall git auth status          # live check against the remote; no secret is shown
+total-recall git auth map <host> <KEY>
+total-recall git auth setup           # helper entries for this machine
+```
+
+git asks the auth store through `credential-helper`; the credential goes only to git.
+
+## The git CLI on every node
+
+```bash
+total-recall git cli --json           # version, path, install source, upstream, release notes
+total-recall git cli --all-nodes
+total-recall git cli update           # update git through its installer
+```
+
+The task `cli update --scheduled` runs daily on every node.
+
+## Across the mesh
+
+```bash
+total-recall git fleet --all-nodes    # dirty, unpushed, behind, diverged, stale stashes, abandoned worktrees, unmerged
+total-recall git where <commit>       # machines and checkouts that contain a commit
+```
+
+## Unmerged work
+
+```bash
+total-recall git unmerged [--json]    # this repository
+total-recall git unmerged --registered   # every registered repository
+```
+
+Lists local branches with commits the default branch lacks, linked worktrees with uncommitted
+changes, and detached worktrees holding commits that no branch contains (removing such a worktree
+loses them). A commit counts as landed when the default branch, local or origin, reaches it or holds
+an equivalent patch, so rebased and cherry-picked work is not listed; a squash merge is a different
+patch, so delete the branch once it has landed. Stale worktree records and branches kept on purpose
+(`git config --add totalrecall.keepBranch <name>`) are shown but not counted. Registered brains
+that are not git repositories are skipped.
+
+The plugin declares this report as its `startup_check`, so `total-recall startup check` and
+`brief` show the outstanding count and where it is whenever a session starts.
+
+## Intent
+
+```bash
+total-recall git why <file>:<line>    # blame plus the session, tracker item and rules recorded at commit time
+total-recall git message              # draft a commit message from the diff, tracker and action log
+total-recall git group [--apply]      # split a dirty tree into commits by agent session
+total-recall git resolve [--apply]    # propose conflict resolutions from both sides' intent
+total-recall git bisect-agent <good> <bad>   # first bad commit, with the quality gate as the test
+total-recall git handoff <branch> [--out <file>]   # branch, tracker and memory as one SSSS bundle
+```
+
+Successful commits are recorded with their session and tracker items. A commit message that names
+a decision is saved to memory.
+
+## Repository state
+
+```bash
+total-recall git audit [--json]       # branch, worktree, upstream and stash state
+total-recall git identity [--json]    # commit identity and the identities history publishes
+total-recall git diff --json [--patch] [--cached] [--base <ref>]
+```
+
+An unknown upstream is never reported as zero unpushed commits.
+
+## Using this from an agent
+
+Send every git command here: `total-recall git <git command and arguments>` runs git itself, with
+the same output and exit status, plus sign-in from the auth store and the guards above. Push your
+finished, tested work yourself; never push unfinished work.
+
+```bash
+total-recall git status --short
+total-recall git add -A
+total-recall git commit -m "<message>"
+total-recall git push
+total-recall git fleet --json
+total-recall git unmerged
+total-recall git undo --list
+```
+
+Finish what you start: land a branch or worktree once its work is done, then remove it. `unmerged`
+shows what is still outside the default branch.
+
+A refused commit or push names the rule or the auth key that matched; fix the cause, never bypass
+the guard. Raw commands this plugin owns: `git <command>`.