total-recall-brain 3.40.0 → 3.40.2

package/README.md

@@ -1,71 +1,182 @@
-# Total Recall
+# Total Recall — VibeBrain
 
-**Portable personal memory for any IDE** — open source, with canonical SSSS Markdown and disposable search indexes.
+> **The Vibe Coding Brain & Autonomous Software Factory**  
+> *Your AI Daily Driver: Memory, Rules, Secrets, and 33 Visual Plugins — Automatically Managed Across All Your Devices.*
 
-Total Recall stores rules, preferences, facts and project knowledge. The portable runtime provides validated memory operations, local retrieval, task context and instruction surfaces. Optional capabilities run through explicitly installed plugins. Initialization creates an empty brain.
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Zero Cost Embeddings](https://img.shields.io/badge/Embeddings-Zero--Cost%20Ollama-emerald.svg)](#zero-cost-local-intelligence)
+[![Visual Plugins](https://img.shields.io/badge/Visual%20Plugins-33%20Installed-violet.svg)](#installed-plugins--capabilities)
+[![Spec: SSSS 0.9](https://img.shields.io/badge/Spec-SSSS%200.9-amber.svg)](docs/SSSS.md)
 
-## Memory CLI
+---
 
-```sh
-npm install total-recall-brain
-npx total-recall-memory init --project
-npx total-recall-memory remember preference "Prefer clear, short answers." --project
-npx total-recall-memory recall "short answers" --local --project
-npx total-recall-memory context "Implement a memory change" --action edit,test --project
-npx total-recall-memory compile --project
+## ⚡ Why Total Recall?
+
+Modern software development with AI agents requires more than fragmented chat sessions or fragile prompt snippets. Developers need an integrated environment that remembers project rules, safeguards credentials, and scales from local prototype to autonomous multi-node production.
+
+Total Recall delivers two synchronized engines in one unified system:
+
+1. **The Personal Daily Driver**: A persistent memory layer, secret vault, and semantic CLI across every editor, terminal, and enrolled device.
+2. **The Autonomous Software Factory**: A modular scaffolding system that constructs production applications from battle-tested plugin bricks (`total-recall new <app> --with <bricks>`) with deterministic quality gates.
+
+---
+
+## 🚀 Quickstart (Under 60 Seconds)
+
+### 1. Install Total Recall
+```bash
+npm install -g total-recall-brain
+```
+
+### 2. Initialize Your Project Brain
+```bash
+npx total-recall init --project
+```
+
+### 3. Record Facts, Preferences, and Invariants
+```bash
+# Store project facts and guidelines
+npx total-recall remember preference "Prefer clear, short answers and functional TypeScript code."
+npx total-recall remember invariant "Databases are disposable projections; never back up raw SQL."
+
+# Hybrid vector and keyword recall (zero token cost via local Ollama)
+npx total-recall recall "database backup policy" --local
+```
+
+### 4. Semantic CLI Discovery
+Query over 415 built-in verbs, plugin operations, and composed commands using natural language:
+```bash
+# Ask questions in natural language
+npx total-recall help "how do I buy a domain and configure DNS"
+npx total-recall help "check test code quality"
+npx total-recall help "rotate production credentials"
+```
+
+### 5. Generate Task Rule Capsules
+Before executing tasks, compile verified instructions that fit your model's exact token budget:
+```bash
+npx total-recall context "Configure production DNS and payment webhooks" --action publish,network
 ```
 
-The package preserves the `total-recall` executable, dashboard and plugin scaffold during migration. The isolated memory CLI is available as `total-recall-memory`. Use `npx --package total-recall-brain total-recall-memory <command>` without a local installation.
+---
 
-`context` includes required rules before ranked knowledge. Check `ready: true`; exit 2 means the required rules exceed the selected budget. Increase the explicit budget or curate applicability before continuing.
+## 🏗️ The Software Factory: Owned Modular Bricks
 
-Project memory lives at `<repo>/.agent/skills/total-recall/`; global memory lives at `<home>/.agent/skills/total-recall/`. `--project` and `--global` select the layer. `AGENT_DIR` explicitly pins all layer operations to one agent root. Canonical memory remains separate between roots.
+Never start an application from empty directories again. Total Recall plugins are **vendorable bricks**: when you scaffold a project, the plugin implementation vendors directly into your repository, giving your team full code ownership.
 
-Local retrieval needs no server or embedding provider. Set `TR_EMBEDDINGS_DISABLED=1` for provider-free operation. Semantic search requires a configured provider. Compilation preserves existing embeddings; mutation commands await local indexing.
+```bash
+# Scaffold an entire production application with pre-wired capabilities
+npx total-recall new my-saas-app --with auth,domains,stripe,marketing,code-quality
+```
+
+### Shipped Bricks Include:
+- **`auth`**: Hardware WebAuthn biometric FIDO2 passkeys, OAuth session management, and AES-256 encrypted credential vaults.
+- **`domains`**: Unified registrar purchasing, DNS table synchronization, Mailcow mailboxes, and SPF/DKIM verification.
+- **`stripe`**: Checkout sessions, automated payment intents, webhook signing verification, and refunds.
+- **`marketing`**: SSSS brand vision profiles, fail-closed copy compliance linters, social card auditors, and UTM link attribution.
+- **`code-quality`**: Deterministic test compliance gates, fail-closed linting, and coverage snapshots.
+- **`mesh`**: Tailscale-based encrypted peer-to-peer device mesh, remote execution, and node presence monitoring.
+
+---
+
+## 🧠 Zero-Cost Local Intelligence
 
-Run `total-recall --help` for the current commands. `import` preserves authored rule files and imports validated memory. `lint` validates memory and can validate installed manifests with `--plugins`; feature records require their owning validator.
+Total Recall prioritizes local-first intelligence. While legacy tools impose per-query token fees, Total Recall pairs with local and mesh Ollama instances to deliver fast vector embeddings at zero cost:
 
-## Optional capabilities
+- **Model**: `nomic-embed-text:latest` (768 dimensions)
+- **Local Endpoint**: `http://127.0.0.1:11434` (falls back to mesh cloud nodes)
+- **Content-Hash Incremental Rebuilds**: Skips unchanged vault nodes during surface compilation
+- **Fail-Closed Fallback**: Seamlessly falls back to local keyword token matching when offline
 
-```sh
-total-recall plugin install /path/to/capability --global
-total-recall plugin list
-total-recall plugin info capability-id
-total-recall capability-command --help
-total-recall plugin remove capability-id --global
+```bash
+# Rebuild surfaces and vector indices
+npx total-recall compile
+
+# Inspect vector model coverage and benchmarks
+npx total-recall embeddings status
 ```
 
-Local directories and Git sources use the same manifest validation, canonical installation records and artifact digest. Installed `cli` and `commands` declarations use an isolated child process with bounded output and timeout. Removal disables dispatch and preserves memory and recorded installation history; reinstalling the same artifact restores its digest.
+---
+
+## 👥 Personas & Workflows
+
+### 🎨 For Makers
+- **Problem**: Context windows reset constantly, losing instructions and design preferences.
+- **Solution**: Total Recall automatically injects relevant memory, design tokens, and image generation studio tools into any client.
+
+### 🛠️ For Builders
+- **Problem**: Wiring authentication, DNS records, and quality gates from scratch drains engineering momentum.
+- **Solution**: Vendor pre-built, tested plugin bricks with `total-recall new` and maintain deterministic CI gates locally.
 
-Plugins are trusted code with the operator's OS permissions. A child process protects the host from handler exits and output interference; it provides no OS sandbox. Background jobs, services, interfaces, distribution and feature-specific validation belong to the capability owner.
+### 🏢 For Founders
+- **Problem**: Managing scattered API keys and multi-server fleet deployments creates operational risk.
+- **Solution**: Encrypt all secrets in local AES-256 stores (`total-recall auth secret`) and coordinate multi-node execution over the secure mesh network.
 
-Dashboard plugin interfaces run in scripts-only frames with an opaque origin. They cannot access dashboard DOM/storage or fetch services directly. Self-contained owner modules receive themed variables and a `host.run(subcommand, args)` bridge restricted to manifest-declared commands and server authorization. Native command handlers retain the trust boundary described above. Never embed secret values in generated interface code.
+### 📈 For Sellers
+- **Problem**: Coordinating direct line telephony, customer messaging, and ticket inventory requires multiple disconnected services.
+- **Solution**: Run integrated phone dialers, SMS pooling, and tiered ticket reservations directly from your terminal.
 
-## Memory HTTP service
+---
 
-After installing the package locally:
+## 🔌 Visual Plugin Ecosystem (33 Installed Plugins)
 
-```sh
-AGENT_DIR=/path/to/agent TR_EMBEDDINGS_DISABLED=1 total-recall-memory init
-AGENT_DIR=/path/to/agent HOST=127.0.0.1 PORT=3900 node node_modules/total-recall-brain/src/server/memory-server.mjs
+Total Recall plugins feature bespoke animated interfaces with zero simulated state, touch-first ergonomics, and live operational controls:
+
+| Plugin | Namespace | Role |
+| :--- | :--- | :--- |
+| **Auth** | `auth` | Biometric WebAuthn passkeys, OAuth sessions, and AES-256 secrets |
+| **Marketing** | `marketing` | Brand vision, copy compliance linter, SEO auditor, and campaign UTMs |
+| **Domains** | `domains` | Domain purchases, DNS records, Mailcow mailboxes, and SPF/DKIM alignment |
+| **Stripe** | `stripe` | Payment processing, checkout sessions, and webhook signature verification |
+| **Code Quality** | `code-quality` | Fail-closed deterministic code gates and test reports |
+| **Embeddings** | `embeddings` | Local zero-cost embedding model management and benchmarks |
+| **Mesh** | `mesh` | Encrypted Tailscale control server, remote execution, and node presence |
+| **Hermes** | `hermes` | Hermes Agent runtime supervision and messaging gateway |
+| **CLI Agents** | `cli-agents` | Authenticated terminal coding agent orchestration and documentation |
+| **OpenWiki** | `openwiki` | Multi-repository documentation graph and knowledge ingestion |
+| **Phone** | `phone` | Direct telephony dialer, call session control, and inventory |
+| **Text** | `text` | Direct SMS/MMS messaging, number pooling, and message threads |
+| **Tickets** | `tickets` | Tiered ticket types, reservations, and double-entry ledger audits |
+| **Security** | `security` | Machine security scanning, OS hardening, and credential audits |
+| **Decision** | `decision` | Typed SSSS decision sets with confidence rankings and event logging |
+| **Design** | `design` | Design system synthesis, theme tokens, and CSS variable generation |
+
+---
+
+## 💻 Composable CLI Architecture
+
+Total Recall eliminates script sprawl through its dynamic composable CLI engine. Compose reusable multi-step workflows with full version history and rollback capabilities:
+
+```bash
+# Run configured repository quality gates
+npx total-recall code-quality-check
+
+# Inspect latest gate report
+npx total-recall code-quality-report
 ```
 
-In the source checkout, `npm run start:memory` selects the memory server. `npm start` preserves the existing dashboard service.
+---
 
-The service exposes memory, context, instructions, rules, scoped keys and authentication. `/health` reports initialization, node count, runtime and package version. Health requires authentication except direct local access. `/.well-known/total-recall.json` lists available memory endpoints. Configure a scoped credential with `total-recall key --help` or `generate-pat --help` before remote use.
+## 🛠️ Development & Quality Gates
 
-The `total-recall-brain/memory` export provides `createMemoryApp()`. Existing package and secret-store exports remain available for installed consumers.
+Total Recall source code enforces strict deterministic quality checks:
 
-## Source and migration
+```bash
+# Run unit and integration tests
+npm test
 
-The source checkout and this compatible npm release retain existing product implementations during migration, including the dashboard, update command and plugin creation scaffold. The package gate verifies the complete memory file inventory alongside these compatibility surfaces and excludes private brain state. The isolated memory entrypoint does not load the product worker or dashboard. A default memory-only package requires a breaking release and completed capability migration.
+# Verify npm package distribution inventory
+npm run check:package
 
-Versions ahead of the public npm release display **Preview features**. Host updates and older registered projects are reported separately; updating projects never downgrades a preview installation.
+# Verify SSSS specification schema registry lock
+npm run check:ssss-registry
 
-The [prior product README](docs/reference/legacy-product-readme.md) preserves the original documentation. The [active core/plugin project](docs/projects/in-progress/TR_CORE_PLUGIN_SPLIT/TR_CORE_PLUGIN_SPLIT_PROJECT_TRACKER.md) records implementation and verification; its unfinished acceptance items are not release claims.
+# Verify scaffold plugin synchronization
+node scripts/sync-scaffold-plugins.mjs --check
+```
 
-## Development
+---
 
-The source uses Node ESM and Vitest. Run the repository's configured background gates on its sanctioned test host. `npm run check:package` inspects npm's actual file inventory; `npm run check:ssss-registry` verifies the composed registry lock. Clean installed-artifact and native service checks complement the source suite.
+## 📄 License
 
-MIT license. See [LICENSE](LICENSE).
+MIT License. See [LICENSE](LICENSE) for full details.

package/bin/total-recall.mjs

@@ -40,76 +40,7 @@ import path from 'node:path';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_DIR = path.join(__dirname, '..', 'src', 'cli');
 
-const COMMANDS = {
-  app:      'app/index.mjs',
-  init:     'init.mjs',
-  setup:    'setup.mjs',
-  start:    'start.mjs',
-  startup:  'startup.mjs',
-  deploy:   'deploy.mjs',
-  doctor:   'doctor.mjs',
-  backup:   'backup.mjs',
-  dream:    'dream.mjs',
-  lint:     'lint.mjs',
-  daemon:   'daemon.mjs',
-  restore:  'restore.mjs',
-  upgrade:  'upgrade.mjs',
-  update:   'update.mjs',
-  friction: 'friction.mjs',
-  chat:     'chat.mjs',
-  status:   'status.mjs',
-  remember: 'remember.mjs',
-  forget:   'forget.mjs',
-  edit:     'edit.mjs',
-  recall:   'recall.mjs',
-  context:  'context.mjs',
-  rules:    'rules.mjs',
-  search:   'recall.mjs',
-  research: 'research.mjs',
-  proposals: 'proposals.mjs',
-  proposal:  'proposals.mjs',
-  task:     'task.mjs',
-  share:    'share.mjs',
-  'generate-pat': 'generate-pat.mjs',
-  key:      'key.mjs',
-  keys:     'key.mjs',
-  pat:      'key.mjs',
-  'hash-password': 'hash-password.mjs',
-  'reset-password': 'reset-password.mjs',
-  compile:  'rebuild.mjs',
-  rebuild:  'rebuild.mjs',
-  snapshot: 'snapshot.mjs',
-  migrate:  'migrate.mjs',
-  backfill: 'backfill.mjs',
-  ingest:   'ingest.mjs',
-  import:   'import-rules.mjs',
-  connect:  'connect.mjs',
-  sync:     'sync.mjs',
-  relay:    'relay.mjs',
-  uninstall: 'uninstall.mjs',
-  map:      'map.mjs',
-  brain:    'brain.mjs',
-  config:   'config.mjs',
-  skill:    'skill.mjs',
-  'project-id': 'project-id.mjs',
-  api:      'api.mjs',
-  brief:    'brief.mjs',
-  group:    'group.mjs',
-  groups:   'group.mjs',
-  help:     'help.mjs',
-  collab:   'collab.mjs',
-  command:  'command.mjs',
-  export:   'export.mjs',
-  harness:  'harness.mjs',
-  watch:    'rebuild.mjs',
-  agent:    'agent.mjs',
-  agents:   'agent.mjs',
-  new:      'new.mjs',
-  plugin:   'plugin/index.mjs',
-  plugins:  'plugin/index.mjs',
-  scaffold: 'plugin/scaffold-cmd.mjs',
-  'scaffold-plugin': 'plugin/scaffold-cmd.mjs',
-};
+import { CLI_COMMANDS as COMMANDS } from '../src/core/cli-commands.mjs';
 async function printHelp() {
   let pluginsSection = '';
   try {
@@ -135,6 +66,8 @@ async function printHelp() {
     connect <client>    Wire IDE surface (Cursor, Claude, Codex, Grok, Replit, Lovable)
     remember / forget / edit   Write-path memory (SSSS vault)
     recall              Read-path hybrid search
+    context "<task>"    Required-rule capsule to read before acting (require ready:true)
+    auth secret <cmd>   Credentials (the only secrets path): list|get|set|rotate|remote deploy|diff-env|export-env
     compile             Rebuild instruction surfaces
     dream               Memory consolidation cycle
     proposals <cmd>     Review / apply optimizer proposals (list|apply|revert)
@@ -163,17 +96,23 @@ ${pluginsSection}
     npx total-recall remember fact "The API uses port 3000."
     npx total-recall dream
     npx total-recall skill track .
-    npx total-recall secret list
+    npx total-recall auth secret list
 
   Options:
     --help, -h          Show this help
     --version, -v       Show version
 `);
+  console.log(`  Complete built-in command list:\n    ${Object.keys(COMMANDS).join(', ')}\n`);
 }
 
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
+  // These names must not reappear through generic API or composed routing.
+  if (command === 'secret' || command === 'secrets') {
+    console.error('Credential commands belong to the auth plugin. Use total-recall auth secret --help.');
+    process.exit(1);
+  }
 
   if (!command || command === '--help' || command === '-h') {
     await printHelp();
@@ -201,15 +140,16 @@ async function main() {
       const { discoverPlugins } = await import('../src/core/plugin-loader.mjs');
       const plugins = discoverPlugins(process.cwd());
       for (const p of plugins) {
-        if (p.valid && (p.manifest.cli?.command === command || (p.id === 'auth' && (command === 'secret' || command === 'secrets')))) {
+        if (p.valid && p.manifest.cli?.command === command) {
           const handlerRel = p.manifest.cli.handler;
           if (handlerRel) {
             const { runPluginCommand } = await import('../src/core/plugin-runner.mjs');
-            const pluginArgs = (command === 'secret' || command === 'secrets')
-              ? ['secret', ...args.slice(1)]
-              : args.slice(1);
+            const pluginArgs = args.slice(1);
             const result = await runPluginCommand(p, { args: pluginArgs, stdin: 'inherit' });
-            if (result.output) process.stdout.write(result.output);
+            if (result.stdout !== undefined) {
+              if(result.stdout)process.stdout.write(result.stdout);
+              if(result.stderr)process.stderr.write(result.stderr);
+            }else if(result.output)process.stdout.write(result.output);
             process.exit(result.ok ? 0 : (result.exitCode || 1));
           }
         }

package/docs/reference/cli-reference.md

@@ -376,18 +376,18 @@ Issue labels and grant scoped Bearer Personal Access Tokens (PATs).
 Manage API keys and credentials (stored in `secrets.enc`, not in the memory vault).
 - **Usage**:
   ```bash
-  npx total-recall secret set <key> <value> [options]
-  npx total-recall secret generate <key> [--bytes 32] [--format hex|base64url]
-  npx total-recall secret get <key>
-  npx total-recall secret list
-  npx total-recall secret rotate <key> <value>
-  npx total-recall secret delete <key>
+  npx total-recall auth secret set <key> <value> [options]
+  npx total-recall auth secret generate <key> [--bytes 32] [--format hex|base64url]
+  npx total-recall auth secret get <key>
+  npx total-recall auth secret list
+  npx total-recall auth secret rotate <key> <value>
+  npx total-recall auth secret delete <key>
 
   # Executed rotation (3.22.0+)
-  npx total-recall secret rotation-status [--json]
-  npx total-recall secret rotate-auto <key> [--export-env]
-  npx total-recall secret rotate-browser <key> [--headless] [--print-only]
-  npx total-recall secret browser-logout
+  npx total-recall auth secret rotation-status [--json]
+  npx total-recall auth secret rotate-auto <key> [--export-env]
+  npx total-recall auth secret rotate-browser <key> [--headless] [--print-only]
+  npx total-recall auth secret browser-logout
   ```
 - **Options for set**:
   - `--provider <name>`: E.g., openai, anthropic.

package/extension/background.js

@@ -3,7 +3,7 @@
 // badge, and capture. The side panel and content script talk to the brain
 // through here or through BrainClient directly.
 
-importScripts('lib/brain-client.js', 'lib/ui-helpers.js');
+importScripts('config.js', 'lib/brain-client.js', 'lib/ui-helpers.js');
 
 const Brain = self.BrainClient;
 const UI = self.TRUi;
@@ -36,7 +36,11 @@ chrome.runtime.onInstalled.addListener(async (details) => {
   for (const menu of menus) {
     chrome.contextMenus.create({ ...menu, documentUrlPatterns: ['http://*/*', 'https://*/*'] });
   }
-  if (details.reason === 'install') chrome.runtime.openOptionsPage();
+  // If already pre-configured with a token, do not interrupt with the options page.
+  const config = await Brain.getConfig();
+  if (details.reason === 'install' && !config.pat) {
+    chrome.runtime.openOptionsPage();
+  }
 });
 
 // ---------------------------------------------------------------------------

package/extension/config.js

@@ -0,0 +1,8 @@
+// Total Recall extension configuration
+// When downloaded from the Total Recall dashboard, this file is pre-populated
+// with your brain's address and an automatically generated access token.
+self.TOTAL_RECALL_CONFIG = self.TOTAL_RECALL_CONFIG || {
+  brainUrl: 'http://127.0.0.1:3000',
+  pat: '',
+  activeBrainId: 'global'
+};

package/extension/lib/brain-client.js

@@ -28,11 +28,36 @@
   }
 
   async function getConfig() {
+    const pre = (typeof self !== 'undefined' && self.TOTAL_RECALL_CONFIG) || {};
     const [local, sync] = await Promise.all([
-      chrome.storage.local.get(['brainUrl', 'pat']),
+      chrome.storage.local.get(['brainUrl', 'pat', 'activeBrainId']),
       chrome.storage.sync.get(['brainUrl', 'pat', 'activeBrainId']),
     ]);
 
+    let pat = local.pat || sync.pat || pre.pat || '';
+    let brainUrl = normalizeUrl(local.brainUrl || sync.brainUrl || pre.brainUrl || DEFAULT_BRAIN_URL);
+    let activeBrainId = local.activeBrainId || sync.activeBrainId || pre.activeBrainId || 'global';
+
+    // If local storage is empty, attempt to read bundled config.json fallback
+    if (!pat && typeof chrome !== 'undefined' && chrome.runtime?.getURL) {
+      try {
+        const res = await fetch(chrome.runtime.getURL('config.json'));
+        if (res.ok) {
+          const json = await res.json();
+          if (json && json.pat) {
+            pat = json.pat;
+            if (json.brainUrl) brainUrl = normalizeUrl(json.brainUrl);
+            if (json.activeBrainId) activeBrainId = json.activeBrainId;
+          }
+        }
+      } catch { /* config.json is optional */ }
+    }
+
+    // Automatically initialize local storage with pre-configured settings
+    if (!local.pat && pat) {
+      await chrome.storage.local.set({ pat, brainUrl, activeBrainId });
+    }
+
     // PATs belong in extension-local storage only; migrate any legacy synced copy.
     if (sync.pat && !local.pat) {
       await chrome.storage.local.set({ pat: sync.pat });
@@ -41,9 +66,9 @@
     if (sync.pat) await chrome.storage.sync.remove('pat');
 
     return {
-      brainUrl: normalizeUrl(local.brainUrl || sync.brainUrl),
-      pat: local.pat || '',
-      activeBrainId: sync.activeBrainId || 'global',
+      brainUrl,
+      pat,
+      activeBrainId,
     };
   }
 

package/extension/options/options.html

@@ -114,6 +114,7 @@
     <footer class="foot" id="foot"></footer>
   </div>
 
+  <script src="../config.js"></script>
   <script src="../lib/brain-client.js"></script>
   <script src="../lib/ui-helpers.js"></script>
   <script src="options.js"></script>

package/extension/sidepanel/sidepanel.html

@@ -236,6 +236,7 @@
     <div class="toast" id="toast" role="status" aria-live="polite" hidden></div>
   </div>
 
+  <script src="../config.js"></script>
   <script src="../lib/brain-client.js"></script>
   <script src="../lib/ui-helpers.js"></script>
   <script src="sidepanel.js"></script>