total-recall-brain 3.45.0 → 3.46.1

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

@@ -0,0 +1,110 @@
+---
+name: Embeddings
+description: Local embedding provider, model roster and vault vector coverage for a Total Recall brain.
+colors:
+  primary: "#06b6d4"
+  primary-hover: "#22d3ee"
+  background: "#07171d"
+  surface: "#0e2a35"
+  line: "#164e63"
+  text: "#ecfeff"
+  muted: "#67e8f9"
+  on-primary: "#07171d"
+  ok: "#10b981"
+  warn: "#f59e0b"
+  danger: "#ef4444"
+typography:
+  body:
+    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
+    fontSize: 13px
+    fontWeight: 400
+  label:
+    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
+    fontSize: 11px
+    fontWeight: 700
+  mono:
+    fontFamily: "'JetBrains Mono', 'Fira Code', monospace"
+    fontSize: 12px
+    fontWeight: 600
+  figure:
+    fontFamily: "'JetBrains Mono', 'Fira Code', monospace"
+    fontSize: 28px
+    fontWeight: 800
+rounded:
+  sm: 4px
+  md: 6px
+  lg: 8px
+spacing:
+  xs: 4px
+  sm: 8px
+  md: 12px
+  lg: 16px
+components:
+  section:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.text}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.md}"
+  locality-chip:
+    textColor: "{colors.ok}"
+    typography: "{typography.label}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.xs}"
+  coverage-figure:
+    textColor: "{colors.text}"
+    typography: "{typography.figure}"
+  count-row:
+    textColor: "{colors.muted}"
+    typography: "{typography.mono}"
+  model-row:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.text}"
+    typography: "{typography.mono}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.sm}"
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.label}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.sm}"
+  button-primary-hover:
+    backgroundColor: "{colors.primary-hover}"
+  notice:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.muted}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.sm}"
+---
+
+# Embeddings
+
+## Overview
+
+An operator console for the vectors behind Total Recall search. It answers four questions, in this order: which provider serves vectors and whether text stays on this machine, how much of the vault has a usable vector, which models the endpoint offers, and how fast the selected model embeds. Every figure comes from the plugin's own JSON operations. Anything not reported renders as a dash, never as a guess.
+
+## Colors
+
+Deep teal surfaces with a cyan primary. Locality and health use the state colors: `ok` for local and current, `warn` for remote, unknown or partial, and `danger` for unreachable or failed. Text uses `text` on `surface`, with `muted` for labels and secondary counts.
+
+## Typography
+
+Sans-serif for prose and labels. Monospace for anything an operator might copy: endpoints, model names, counts and timings. A single large monospace `figure` carries the usable-coverage percentage.
+
+## Components
+
+- `section`: a bordered surface panel per question (provider, coverage, models, benchmark, pull).
+- `locality-chip`: the local, remote, unknown or disabled verdict, colored by state.
+- `coverage-figure`: the usable-vector percentage.
+- `count-row`: one labelled count (usable, stale, wrong width, missing, orphaned).
+- `model-row`: one model with its width, capability and selection.
+- `button-primary`: an operator-triggered action. Touch targets are at least 44px.
+- `notice`: unavailable, failed or explanatory text.
+
+## Do's and Don'ts
+
+- Do show a non-`ok` index state by name. Don't render it as 0%.
+- Do keep provider state separate from credentials. Hosted fallback keys belong to the Auth owner and are never displayed.
+- Don't claim "on-device" unless `locality` is `local`.
+- Don't run benchmark or pull on load.
+- Respect `prefers-reduced-motion`.

package/scaffold/.agent/skills/total-recall/plugins/embeddings/package-lock.json

@@ -1,18 +1,18 @@
 {
   "name": "tr-plugin-embeddings",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-embeddings",
-      "version": "0.1.4",
+      "version": "0.2.0",
       "license": "MIT",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
-        "total-recall-brain": "3.44.0"
+        "total-recall-brain": "3.45.0"
       }
     },
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -5539,9 +5539,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.44.0",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.44.0.tgz",
-      "integrity": "sha512-VNPaIO9zsSwoxAsJ5ByIQBP9zPpLq4RiQO7Vrex4rBOHFQJT50P7utcZiLMSZTyZJU4C/m5uB8qTCSBMp6+l6Q==",
+      "version": "3.45.0",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.45.0.tgz",
+      "integrity": "sha512-HDYfROazZbsLHQsFPnlBcSpe1HL1QEi7JG8x/eNRUI06RxVQsZWl8LwBo2lTWjWRDrKmCy7BUmSXQDuWF3lrEw==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

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

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-embeddings",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "description": "Local embedding model management: provider/model status, benchmark, index build and coverage",
   "scripts": {
@@ -13,6 +13,7 @@
     "plugin.json",
     "README.md",
     "LICENSE",
+    "DESIGN.md",
     "ui/"
   ],
   "dependencies": {

package/scaffold/.agent/skills/total-recall/plugins/embeddings/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "embeddings",
   "name": "Embeddings",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Local embedding model management: provider/model status, benchmark, index build and coverage",
   "license": "MIT",
   "branding": {
@@ -58,21 +58,24 @@
       }
     ]
   },
-  "card": {
-    "handler": "./ui/card.js",
-    "element": "tr-embeddings-card"
-  },
   "ui": {
+    "home": "home",
+    "design_tokens": "DESIGN.md",
     "elements": [
       {
-        "id": "card",
-        "kind": "card",
-        "tag": "tr-embeddings-card",
-        "module": "ui/card.js",
-        "description": "Embeddings card face"
+        "id": "home",
+        "kind": "panel",
+        "tag": "tr-embeddings-home",
+        "module": "ui/home.js",
+        "description": "Embeddings page: provider and locality, vault coverage, model roster, credentials ownership, benchmark and pull"
       }
     ]
   },
+  "auth": {
+    "plugin": "auth",
+    "methods": ["passkey", "google-oauth2"],
+    "session_verification": true
+  },
   "status": {
     "command": "status",
     "refresh_seconds": 60

package/scaffold/.agent/skills/total-recall/plugins/embeddings/ui/chunks/benchmark.md

@@ -0,0 +1,49 @@
+---
+type: ui-chunk:chunk
+plugin: embeddings
+id: benchmark
+title: Embedding benchmark
+description: Measures milliseconds per embedding for the selected local model using a neutral sentence, verifies each vector is 768 wide, and projects the time to embed the whole vault.
+timestamp: '2026-11-08T08:12:00Z'
+intents:
+  - benchmark embedding speed
+  - estimate time to embed the vault
+surfaces:
+  - page
+operations:
+  - benchmark
+data:
+  - benchmark:/ok
+  - benchmark:/reason
+  - benchmark:/url
+  - benchmark:/locality
+  - benchmark:/model
+  - benchmark:/dims
+  - benchmark:/samples
+  - benchmark:/ms_per_embedding
+  - benchmark:/min_ms
+  - benchmark:/max_ms
+  - benchmark:/vault_nodes
+  - benchmark:/projected_minutes
+  - benchmark:/completed
+panel: home
+---
+<style>
+  .emb-benchmark { color: var(--colors-text, #ecfeff); background: var(--colors-surface, #0e2a35); border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-md, 6px); padding: var(--spacing-md, 12px); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 13px; }
+  .emb-benchmark h3 { margin: 0 0 var(--spacing-sm, 8px); font-size: 11px; letter-spacing: 0.05em; text-transform: uppercase; color: var(--colors-muted, #67e8f9); }
+  .emb-benchmark dl { display: grid; grid-template-columns: max-content 1fr; gap: var(--spacing-xs, 4px) var(--spacing-md, 12px); margin: 0; }
+  .emb-benchmark dt { color: var(--colors-muted, #67e8f9); }
+  .emb-benchmark dd { margin: 0; }
+  .emb-benchmark code { font-family: 'JetBrains Mono', 'Fira Code', monospace; font-size: 12px; }
+  .emb-benchmark p { margin: var(--spacing-sm, 8px) 0 0; color: var(--colors-muted, #67e8f9); }
+</style>
+<section class="emb-benchmark" data-design-component="section">
+  <h3>Embedding benchmark</h3>
+  <dl>
+    <dt>Reports</dt><dd>Average, minimum and maximum milliseconds per embedding, the sample count, and the model and endpoint measured.</dd>
+    <dt>Projection</dt><dd>Average time multiplied by the vault node count, in minutes.</dd>
+    <dt>Bounds</dt><dd>1 to 20 samples (default 10), within a 280-second deadline.</dd>
+    <dt>Refuses</dt><dd>A remote, upstream or missing model. No vault text is sent.</dd>
+  </dl>
+  <p>Run it from the Embeddings page. It never runs on its own.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/embeddings/ui/chunks/coverage.md

@@ -0,0 +1,53 @@
+---
+type: ui-chunk:chunk
+plugin: embeddings
+id: coverage
+title: Vault vector coverage
+description: How many vault nodes have a current, correct-width vector in the index, and why the rest are not usable. Reads the index without modifying it.
+timestamp: '2026-11-08T08:12:00Z'
+intents:
+  - check vault vector coverage
+  - find stale or missing embeddings
+surfaces:
+  - page
+operations:
+  - coverage
+data:
+  - coverage:/ok
+  - coverage:/brain
+  - coverage:/state
+  - coverage:/reason
+  - coverage:/vault_nodes
+  - coverage:/parse_errors
+  - coverage:/rows
+  - coverage:/embedded
+  - coverage:/stale
+  - coverage:/mismatched
+  - coverage:/orphaned
+  - coverage:/missing
+  - coverage:/percent
+  - coverage:/model
+  - coverage:/models
+  - coverage:/db_bytes
+panel: home
+---
+<style>
+  .emb-coverage { color: var(--colors-text, #ecfeff); background: var(--colors-surface, #0e2a35); border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-md, 6px); padding: var(--spacing-md, 12px); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 13px; }
+  .emb-coverage h3 { margin: 0 0 var(--spacing-sm, 8px); font-size: 11px; letter-spacing: 0.05em; text-transform: uppercase; color: var(--colors-muted, #67e8f9); }
+  .emb-coverage ul { list-style: none; margin: 0; padding: 0; display: grid; gap: var(--spacing-xs, 4px); }
+  .emb-coverage li { display: flex; justify-content: space-between; gap: var(--spacing-md, 12px); font-family: 'JetBrains Mono', 'Fira Code', monospace; font-size: 12px; color: var(--colors-muted, #67e8f9); }
+  .emb-coverage li span:first-child { color: var(--colors-text, #ecfeff); }
+  .emb-coverage code { font-family: 'JetBrains Mono', 'Fira Code', monospace; font-size: 12px; }
+  .emb-coverage p { margin: var(--spacing-sm, 8px) 0 0; color: var(--colors-muted, #67e8f9); }
+</style>
+<section class="emb-coverage" data-design-component="section">
+  <h3>Vault vector coverage</h3>
+  <ul>
+    <li data-design-component="count-row"><span>usable</span><span>current text hash, 768 finite numbers</span></li>
+    <li data-design-component="count-row"><span>stale</span><span>the node changed after it was embedded</span></li>
+    <li data-design-component="count-row"><span>wrong width</span><span>the vector is not 768 numbers</span></li>
+    <li data-design-component="count-row"><span>missing</span><span>the node has no row</span></li>
+    <li data-design-component="count-row"><span>orphaned</span><span>the row has no active node</span></li>
+  </ul>
+  <p>The percentage counts usable vectors out of all <code>memory</code> and <code>plugin_record</code> nodes. A missing or unreadable index is reported by its state, not as 0%. Rebuild with <code>total-recall compile</code>.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/embeddings/ui/chunks/models.md

@@ -0,0 +1,43 @@
+---
+type: ui-chunk:chunk
+plugin: embeddings
+id: models
+title: Embedding models
+description: Every model on the resolved Ollama endpoint, with its declared embedding capability, vector width, vault compatibility, upstream flag and which one is selected.
+timestamp: '2026-11-08T08:12:00Z'
+intents:
+  - list embedding models
+  - see which model can embed the vault
+surfaces:
+  - page
+operations:
+  - models
+data:
+  - models:/url
+  - models:/reachable
+  - models:/locality
+  - models:/vault_dims
+  - models:/selected
+  - models:/models
+  - models:/attempts
+panel: home
+---
+<style>
+  .emb-models { color: var(--colors-text, #ecfeff); background: var(--colors-surface, #0e2a35); border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-md, 6px); padding: var(--spacing-md, 12px); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 13px; }
+  .emb-models h3 { margin: 0 0 var(--spacing-sm, 8px); font-size: 11px; letter-spacing: 0.05em; text-transform: uppercase; color: var(--colors-muted, #67e8f9); }
+  .emb-models ul { list-style: none; margin: 0; padding: 0; display: grid; gap: var(--spacing-xs, 4px); }
+  .emb-models li { background: var(--colors-background, #07171d); border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-sm, 4px); padding: var(--spacing-sm, 8px); }
+  .emb-models code { font-family: 'JetBrains Mono', 'Fira Code', monospace; font-size: 12px; }
+  .emb-models .ok { color: var(--colors-ok, #10b981); }
+  .emb-models .warn { color: var(--colors-warn, #f59e0b); }
+  .emb-models p { margin: var(--spacing-sm, 8px) 0 0; color: var(--colors-muted, #67e8f9); }
+</style>
+<section class="emb-models" data-design-component="section">
+  <h3>Embedding models</h3>
+  <ul>
+    <li data-design-component="model-row"><span class="ok">vault-compatible</span>: the model declares the <code>embedding</code> capability, and its family width is 768.</li>
+    <li data-design-component="model-row"><span class="ok">selected</span>: the pinned <code>TR_OLLAMA_EMBED_MODEL</code> when compatible, otherwise the smallest compatible model.</li>
+    <li data-design-component="model-row"><span class="warn">upstream</span>: the service relays the model from another machine, so it does not count as local.</li>
+  </ul>
+  <p>When no endpoint answers, the endpoints tried are reported instead of a model list. The Embeddings page shows the live roster.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/embeddings/ui/chunks/pull.md

@@ -0,0 +1,41 @@
+---
+type: ui-chunk:chunk
+plugin: embeddings
+id: pull
+title: Pull an embedding model
+description: Downloads an explicitly named local model onto the configured loopback Ollama endpoint. Refuses non-loopback endpoints and cloud or upstream models.
+timestamp: '2026-11-08T08:12:00Z'
+intents:
+  - install a local embedding model
+  - pull an embedding model
+surfaces:
+  - page
+operations:
+  - pull
+data:
+  - pull:/ok
+  - pull:/model
+  - pull:/url
+  - pull:/locality
+  - pull:/reason
+  - pull:/status
+panel: home
+---
+<style>
+  .emb-pull { color: var(--colors-text, #ecfeff); background: var(--colors-surface, #0e2a35); border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-md, 6px); padding: var(--spacing-md, 12px); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 13px; }
+  .emb-pull h3 { margin: 0 0 var(--spacing-sm, 8px); font-size: 11px; letter-spacing: 0.05em; text-transform: uppercase; color: var(--colors-muted, #67e8f9); }
+  .emb-pull ol { margin: 0; padding-left: 1.25em; display: grid; gap: var(--spacing-xs, 4px); }
+  .emb-pull code { font-family: 'JetBrains Mono', 'Fira Code', monospace; font-size: 12px; }
+  .emb-pull .warn { color: var(--colors-warn, #f59e0b); }
+  .emb-pull p { margin: var(--spacing-sm, 8px) 0 0; color: var(--colors-muted, #67e8f9); }
+</style>
+<section class="emb-pull" data-design-component="section">
+  <h3>Pull an embedding model</h3>
+  <ol>
+    <li>Name the model exactly. Nothing is pulled by default.</li>
+    <li>The target is <code>TR_OLLAMA_URL</code>, <code>OLLAMA_HOST</code> or <code>127.0.0.1:11434</code>, and it must be loopback.</li>
+    <li><span class="warn">Refused:</span> models that are cloud-hosted or relayed from another machine.</li>
+    <li>The download may take up to ten minutes. The result names the model and endpoint, or the reason for failure.</li>
+  </ol>
+  <p>This changes the endpoint's model store. Start it from the Embeddings page.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/embeddings/ui/chunks/status.md

@@ -0,0 +1,59 @@
+---
+type: ui-chunk:chunk
+plugin: embeddings
+id: status
+title: Embedding provider status
+description: Which provider and model serve vectors for this brain, whether text sent for embedding stays on this machine, and how much of the vault has a usable vector.
+timestamp: '2026-11-08T08:12:00Z'
+intents:
+  - check which embedding model is active
+  - check whether embeddings run locally
+  - check vault vector coverage
+surfaces:
+  - page
+operations:
+  - status
+data:
+  - status:/provider
+  - status:/endpoint
+  - status:/locality
+  - status:/local
+  - status:/selected_model
+  - status:/embedding_dims
+  - status:/hosted_fallback
+  - status:/reason
+  - status:/attempts
+  - status:/brain/state
+  - status:/brain/reason
+  - status:/brain/vault_nodes
+  - status:/brain/embedded
+  - status:/brain/percent
+  - status:/brain/stale
+  - status:/brain/mismatched
+  - status:/brain/missing
+  - status:/brain/orphaned
+  - status:/brain/model
+panel: home
+---
+<style>
+  .emb-status { color: var(--colors-text, #ecfeff); background: var(--colors-surface, #0e2a35); border: 1px solid var(--colors-line, #164e63); border-radius: var(--rounded-md, 6px); padding: var(--spacing-md, 12px); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 13px; }
+  .emb-status h3 { margin: 0 0 var(--spacing-sm, 8px); font-size: 11px; letter-spacing: 0.05em; text-transform: uppercase; color: var(--colors-muted, #67e8f9); }
+  .emb-status dl { display: grid; grid-template-columns: max-content 1fr; gap: var(--spacing-xs, 4px) var(--spacing-md, 12px); margin: 0; }
+  .emb-status dt { color: var(--colors-muted, #67e8f9); }
+  .emb-status dd { margin: 0; }
+  .emb-status code { font-family: 'JetBrains Mono', 'Fira Code', monospace; font-size: 12px; }
+  .emb-status .local { color: var(--colors-ok, #10b981); }
+  .emb-status .away { color: var(--colors-warn, #f59e0b); }
+  .emb-status p { margin: var(--spacing-sm, 8px) 0 0; color: var(--colors-muted, #67e8f9); }
+</style>
+<section class="emb-status" data-design-component="section">
+  <h3>Embedding provider status</h3>
+  <dl>
+    <dt>Provider</dt><dd><code>ollama</code>, <code>hosted-fallback</code> or <code>disabled</code></dd>
+    <dt>Locality</dt><dd><span class="local" data-design-component="locality-chip">local</span> only when a loopback endpoint serves a non-upstream model. Otherwise <span class="away">remote</span>, <span class="away">unknown</span> or <code>disabled</code>.</dd>
+    <dt>Model</dt><dd>The selected model and its vector width. The vault requires 768 dimensions.</dd>
+    <dt>Coverage</dt><dd>Usable vectors out of vault nodes, with stale, wrong-width, missing and orphaned counts.</dd>
+    <dt>Credentials</dt><dd>Hosted fallback keys stay with the Auth owner and are reported as <code>unknown</code>, never read here.</dd>
+  </dl>
+  <p>Open the Embeddings page for the live reading, the endpoints that were tried, and refresh.</p>
+</section>