total-recall-brain 3.31.0 → 3.32.0

package/frontend/dist/index.html

@@ -17,7 +17,7 @@
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
     <title>Total Recall — Portable Memory</title>
-    <script type="module" crossorigin src="/assets/index-DGMNZi_1.js"></script>
+    <script type="module" crossorigin src="/assets/index-FOJG4jQh.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-C7_Xpk27.css">
   </head>
   <body>

package/frontend/package.json

@@ -16,7 +16,7 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "react-force-graph-3d": "^1.29.1",
-    "react-router-dom": "^7.15.0",
+    "react-router-dom": "^7.18.4",
     "recharts": "^3.9.2",
     "three": "^0.185.1",
     "three-spritetext": "^1.10.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.31.0",
+  "version": "3.32.0",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [
@@ -64,7 +64,7 @@
   "homepage": "https://github.com/gregiteen/total-recall#readme",
   "dependencies": {
     "@simplewebauthn/server": "^13.3.2",
-    "@ssss/cli": "github:gregiteen/ssss#main",
+    "@ssss/cli": "github:gregiteen/ssss#v0.10.0",
     "bcrypt": "^6.0.0",
     "better-sqlite3": "^12.11.1",
     "cookie-parser": "^1.4.7",

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

@@ -39,6 +39,11 @@ An ID is lowercase kebab case, starts with a letter, and is 2–64 characters. `
 - **Agent context:** add `compile: { "generator": "./generator.mjs", "auto": true }` and export `generateContext()` from that file. Only include information useful to the agent; avoid secrets and noisy telemetry.
 - **Memory category:** declare it under `ssss_schemas.categories` using the current manifest schema. Preserve SSSS Markdown and operation-contract writes; do not write vault documents directly.
 
+- **Repo-customized skill:** a layered skill (plugin-owned `core/`, repo-owned files beside it) declares its repo config contract as `core/config.schema.json`, a JSON Schema whose root is an object. Annotate an array with `"x-collection": "<noun>"` (and optionally `"x-key"`, default `name`) to get `<noun> list|add|remove`. An optional `core/detect.mjs` exports `detect({ repoRoot, skillDir })` and returns a proposed config. Users customize the repo layer with `total-recall skill config <id> config set …`, `detect --apply`, or `init`, or with a repo command generated by `total-recall command create <name> --config-for-skill <id>`. Every write validates the whole config and commits a `skill_config` record to the repo's project vault; `config.json` is rebuilt from it. Never tell users to edit `config.json` by hand: `config validate` reports hand edits as drift, and `config import` adopts a pre-existing file. Mark gate-command string fields `"x-command": true`; `skill config <id> check`, `skill status <id>`, and `app verify` confirm each one resolves without running it.
+
+- **App-runtime CLI:** declare `app_cli` in `plugin.json`: `name`, `api: { base_url_env, default_base_url }` (loopback only; operators override it with the env var or `--base-url`), optional `auth: { type: "bearer", token_env }`, and `commands: [{ name, method, path, args }]`. Args are typed (`string|integer|number|boolean`, `choices`, `default`, `required`, `positional`); `{name}` in `path` must be a required arg, other args go to the query (GET/DELETE) or JSON body. `total-recall app cli <plugin> --lang node|python` (or `--adapter flask|nextjs|react|ssss-app`) prints a self-contained file; `--out <file>` writes it. The file runs without Total Recall: exit 0 ok, 1 the app returned an error, 2 usage, 3 unreachable; `--json` prints `{ ok, status, data | error }`. Regenerate after changing the spec; never hand-edit the output.
+- **UI elements:** author each element once as a self-contained custom element: an ES module under the plugin (e.g. `ui/<id>.js`) that imports nothing, calls `customElements.define('<tag>', …)` exactly once, and styles itself only with design-token variables (`var(--color-…)`, `--spacing-…`, `--radius-…`, `--typography-<style>-…`, `--font-family-…`; `--_name` for private ones). No literal colors, not even as `var()` fallbacks. Declare it in `plugin.json` `ui.elements[]`: `id`, `kind` (`panel|form|list|detail|settings|widget`), `tag`, `module`, optional `slot`, typed `props` (set as DOM properties), `events`, the `tokens` it requires and `optional_tokens` it uses with a token fallback; `ui.design_tokens` may point at a neutral default `DESIGN.md`. `total-recall app ui <plugin> --ui web-components|react` (or `--adapter flask|ssss-app|nextjs|react`) with `--tokens <app DESIGN.md>` checks the required tokens and generates `tokens.css`, `elements/<id>.js`, `index.js`, React wrappers (`--typescript` for `.tsx` plus `.d.ts`), and `ui-manifest.json`; `--out <dir>` writes `<dir>/<plugin-id>/`. An app restyles elements by editing its `DESIGN.md` and regenerating; the element files do not change.
+
 ## Validate the actual job
 
 1. Validate `plugin.json` against the installed schema and `total-recall plugin info <id>`.

package/scaffold/.agent/skills/total-recall/SKILL.md

@@ -16,7 +16,6 @@ repo_scoped: true
 > **Only agent skill in this package.** Implementation helpers live in `modules/` (not skills).
 > Openwiki ships with the brain at `openwiki/`.
 
-
 Welcome to the master control skill for the **Total Recall Autonomous AI OS**. > [!NOTE]
 > **Total Recall Architecture:**
 > The Total Recall memory kernel runs as a standalone REST service. Agents interact with the memory vault, perform semantic searches, and compile rules directly using lightweight, filesystem-native REST API calls via standard shell `curl` commands.
@@ -29,7 +28,7 @@ You MUST actively reference and apply this skill under the following specific ru
 
 ### 1. When the user establishes a rule, preference, or correction
 *   **Trigger**: Whenever the user corrects your behavior, shares a coding style, defines an architectural pattern, or establishes a preference you must remember.
-*   **Action**: Autonomously create a new SSSS v2 memory node under `.agent/memory-vault/` and compile the vault.
+*   **Action**: Save the new rule with `npx total-recall remember` in the appropriate category and scope. The CLI validates the node and compiles the vault.
 
 ### 2. When referencing invariants, preferences, and corrections (Intrinsically Known Rules)
 *   **⚠️ MANDATORY**: The compiled instruction files (like `INSTRUCTIONS.md`, `GEMINI.md`, `AGENTS.md`, etc.) contain the **entirety** of active invariants, preferences, and behavior corrections (rules/directives).
@@ -37,7 +36,7 @@ You MUST actively reference and apply this skill under the following specific ru
 
 ### 3. When searching for complex domain knowledge or general facts
 *   **Trigger**: When you need to retrieve deep factual information (e.g. from the `facts/` category) or conceptual domain structures (e.g. from `concepts/`) that are not present in your active instruction files.
-*   **Action**: Use the semantic/lexical hybrid search engine (via the local `recall` command, or `/api/memory/search/semantic` endpoint) along with regular text search (e.g., grep):
+*   **Action**: Use `npx total-recall recall "<query>"` to search memory. Do not read or grep memory-vault files directly.
      *   **Hybrid Search**: Blends cosine-similarity vector search and lexical density TF-IDF keyword matching using Reciprocal Rank Fusion (RRF). This blends intent-based semantic matching with exact keyword accuracy.
      *   **Hierarchical Parent-Child Search**: Memory node bodies are chunked and indexed as children. The vector store searches both the parent node and child chunks, returning matches based on maximum similarity.
      *   **Regular Text Search**: Use grep to locate exact configurations, literal keys, or symbols.
@@ -59,7 +58,7 @@ You MUST actively reference and apply this skill under the following specific ru
 
 ### 5. When you modify, add, or delete files in the memory vault
 *   **Trigger**: Immediately after performing any memory node writes.
-*   **Action**: Rebuild the instruction shims. If using CLI commands (`npx total-recall remember` / `forget`), recompilation runs automatically in the background (asynchronously via detached subprocesses) to minimize latency. If editing vault files directly, trigger manual compilation by sending a POST request to `/api/vault/compile` or running `npx total-recall compile`.
+*   **Action**: The `remember` and `forget` CLI commands compile the instruction shims automatically. Use `npx total-recall compile` only when a manual rebuild is needed; never edit vault files directly.
 
 ### 5b. When handling ANY credential, API key, or password
 Never invent a new place to keep it. It goes in the encrypted secrets store —
@@ -75,6 +74,24 @@ See **TESTS**. The full suite and the quality gates run only on the Mac Mini —
 never on a laptop or the cloud droplet. A single spec file may run on any mesh node. Builds and installs are fine on any machine; build large apps
 on the Mac Mini.
 
+### 5e. When operating any third-party provider (DNS, registrar, hosting, mail, payments, telephony)
+The user's providers are already integrated: their API keys live in the secrets
+store. "Use the API" for a provider means exactly that.
+1. `npx total-recall secret catalog` — find the provider's key(s) by provider tag.
+2. Call the provider's REST API or CLI with the value read inside your process
+   (never echoed, never in argv). Check the provider's current API docs first.
+3. **Do not** fall back to browser automation when an API exists, and **do not**
+   ask the user for a key the catalog already has. Browser only for flows with
+   no API (e.g. a portal-only compliance form).
+4. Prefer targeted writes over bulk ones: edit one DNS record by id, never
+   replace a whole zone by default; read the current state first and verify after.
+5. If a key is missing, find the service that already uses it (its deployed
+   env), import it with `secret set <key> --stdin`, and record where it lives
+   with `remember fact`.
+6. If the agent host's own permission mode blocks an action category (e.g. DNS
+   changes), say so in one line with the exact setting that allows it. Do not
+   argue repeatedly and do not route around it through another tool.
+
 ### 6. When troubleshooting connections, port blocks, or sync errors
 *   **Trigger**: If the REST server is unreachable, ports are blocked, or the upstream sync tool encounters errors.
 *   **Action**: Refer to the active diagnostics manual within this skill to heal the local runtime.
@@ -339,6 +356,18 @@ curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
 
 ## 🧩 SKILLS MANAGEMENT (`skill` subcommand)
 
+### Initializing a new repository
+
+After initializing a project brain, initialize that repository's own
+`.agent/skills/repo-expert/` from its current code, manifests, tests, and
+runtime configuration. `skill generate-expert --repo <repo>` is a starting
+point; review and trim generated output before use, especially directory trees
+that include runtime data. The local expert must declare `repo_scoped: true`
+and pass an identity check against the current repository. Register it in the
+project brain. The global `repo-expert` remains a repository-agnostic discovery
+method; never deploy another project's expert or synchronize local experts
+across repositories.
+
 Two distinct layers. Confusing them is the usual cause of "my edit disappeared".
 
 | Layer | What it is | Commands |
@@ -555,12 +584,6 @@ that dead-ends back at a manual dashboard step.
 
 ---
 
-<!-- BEGIN INJECTED MEMORY: do not edit by hand; rebuilt by total-recall surface -->
-<!-- @route: tfidf, generated_at: 2026-05-21T03:34:14.837Z -->
-
-<!-- END INJECTED MEMORY -->
-
-
 ---
 
 ## 🕸️ MESH / CONTROL SERVER (`mesh` subcommand)

package/src/cli/app/index.mjs

@@ -8,6 +8,8 @@
  *   app create <dir> --plugin <source> [--adapter <id>] [--name <name>] [--force] [--json]
  *   app upgrade <id> --to <source> [--target <dir>] [--adapter <id>] [--dry-run] [--json]
  *   app verify [--target <dir>] [--json]
+ *   app cli <source> [--lang node|python | --adapter <id>] [--out <file>] [--force] [--json]
+ *   app ui <source> [--ui web-components|react | --adapter <id>] [--tokens <DESIGN.md>] [--typescript] [--out <dir>] [--force] [--json]
  */
 
 import path from 'node:path';
@@ -26,6 +28,10 @@ import {
   AppCreateError
 } from '../../core/app-deploy/standalone.mjs';
 import { verifyApplication } from '../../core/app-deploy/verify.mjs';
+import { resolveCapabilitySource } from '../../core/app-deploy/source.mjs';
+import { generateAppCli, languageForAdapter, APP_CLI_LANGUAGES } from '../../core/app-deploy/runtime-cli.mjs';
+import { generateUiElements, writeUiElements, uiTargetForAdapter, UI_TARGETS } from '../../core/app-deploy/ui-elements.mjs';
+import fs from 'node:fs';
 import {
   IncompatibleAdapterError,
   IncompatibleSsssVersionError,
@@ -73,6 +79,23 @@ Commands:
                             --target <dir>     Target application directory (default: cwd)
                             --json             Output verification report as JSON
 
+  cli <source>              Generate the app's own runtime CLI from the plugin's app_cli spec.
+                            The file needs no Total Recall install at run time.
+                            --lang <lang>      node (ESM script) or python (argparse module)
+                            --adapter <id>     Pick the language from the adapter (flask: python; else node)
+                            --out <file>       Write the file (mode 755) instead of printing it
+                            --force            Replace an existing --out file
+                            --json             Output { language, path, sha256, out } as JSON
+
+  ui <source>               Generate the plugin's UI elements for the app, styled by its DESIGN.md.
+                            --ui <target>      web-components (Flask/Jinja, any HTML) or react (React/Next)
+                            --adapter <id>     Pick the target from the adapter (flask, ssss-app: web-components)
+                            --tokens <file>    The app's DESIGN.md (default: the plugin's own default tokens)
+                            --typescript       React wrappers as .tsx
+                            --out <dir>        Write <dir>/<plugin-id>/ (replaced whole) instead of listing files
+                            --force            Replace a previously generated <dir>/<plugin-id>/
+                            --json             Output { target, files, elements, tokens, warnings, out } as JSON
+
 Exit Codes:
   0   Success
   1   User/argument error or internal failure
@@ -418,7 +441,164 @@ export async function run(argv = []) {
     process.exit(0);
   }
 
-  // 5. APP VERIFY
+  // 5. APP CLI
+  else if (sub === 'cli') {
+    let source = null;
+    let language = null;
+    let adapter = null;
+    let out = null;
+    let force = false;
+    let isJson = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === '--json') isJson = true;
+      else if (arg === '--force') force = true;
+      else if (arg === '--lang' && rest[i + 1]) language = rest[++i];
+      else if (arg === '--adapter' && rest[i + 1]) adapter = rest[++i];
+      else if (arg === '--out' && rest[i + 1]) out = rest[++i];
+      else if (!arg.startsWith('--') && !source) source = arg;
+      else {
+        console.error(`\n❌ Unknown or incomplete option: ${arg}\n`);
+        process.exit(1);
+      }
+    }
+    const report = (message, code) => {
+      if (isJson) console.error(JSON.stringify({ error: message }));
+      else console.error(`\n❌ ${message}\n`);
+      process.exit(code);
+    };
+    if (!source) report('Missing capability source. Usage: total-recall app cli <source> --lang node|python [--out <file>]', 1);
+    if (language && adapter) report('Pass --lang or --adapter, not both', 1);
+    if (!language && !adapter) report(`Pass --lang (${APP_CLI_LANGUAGES.join('|')}) or --adapter <id>`, 1);
+    if (adapter) {
+      try {
+        language = languageForAdapter(adapter);
+      } catch (err) {
+        report(err.message, 3);
+      }
+    }
+
+    let generated;
+    let resolved;
+    try {
+      resolved = await resolveCapabilitySource(source);
+      if (!resolved.manifest.app_cli) throw new Error(`Plugin '${resolved.id}' declares no app_cli`);
+      generated = generateAppCli(resolved.manifest.app_cli, { language, source: { id: resolved.id, version: resolved.version } });
+    } catch (err) {
+      if (err?.message?.startsWith('process.exit(')) throw err;
+      report(err.message, 1);
+    } finally {
+      resolved?.cleanup?.();
+    }
+
+    let written = null;
+    if (out) {
+      written = path.resolve(out);
+      if (fs.existsSync(written) && !force) report(`${written} exists; pass --force to replace it`, 1);
+      try {
+        fs.mkdirSync(path.dirname(written), { recursive: true });
+        const tmp = `${written}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, generated.content, { mode: generated.mode });
+        fs.chmodSync(tmp, generated.mode);
+        fs.renameSync(tmp, written);
+      } catch (err) {
+        report(`Could not write ${written}: ${err.message}`, 1);
+      }
+    }
+
+    if (isJson) {
+      console.log(JSON.stringify({ language: generated.language, path: generated.path, sha256: generated.sha256, out: written }));
+    } else if (written) {
+      console.log(`✔ Wrote ${generated.language} app CLI '${generated.spec.name}' to ${written} (suggested path: ${generated.path})`);
+    } else {
+      process.stdout.write(generated.content);
+    }
+    process.exit(0);
+  }
+
+  // 6. APP UI
+  else if (sub === 'ui') {
+    let source = null;
+    let target = null;
+    let adapter = null;
+    let tokens = null;
+    let out = null;
+    let typescript = false;
+    let force = false;
+    let isJson = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === '--json') isJson = true;
+      else if (arg === '--force') force = true;
+      else if (arg === '--typescript') typescript = true;
+      else if (arg === '--ui' && rest[i + 1]) target = rest[++i];
+      else if (arg === '--adapter' && rest[i + 1]) adapter = rest[++i];
+      else if (arg === '--tokens' && rest[i + 1]) tokens = rest[++i];
+      else if (arg === '--out' && rest[i + 1]) out = rest[++i];
+      else if (!arg.startsWith('--') && !source) source = arg;
+      else {
+        console.error(`\n❌ Unknown or incomplete option: ${arg}\n`);
+        process.exit(1);
+      }
+    }
+    const report = (message, code) => {
+      if (isJson) console.error(JSON.stringify({ error: message }));
+      else console.error(`\n❌ ${message}\n`);
+      process.exit(code);
+    };
+    if (!source) report('Missing capability source. Usage: total-recall app ui <source> --ui web-components|react [--tokens DESIGN.md] [--out <dir>]', 1);
+    if (target && adapter) report('Pass --ui or --adapter, not both', 1);
+    if (!target && !adapter) report(`Pass --ui (${UI_TARGETS.join('|')}) or --adapter <id>`, 1);
+    if (adapter) {
+      try {
+        target = uiTargetForAdapter(adapter);
+      } catch (err) {
+        report(err.message, 3);
+      }
+    }
+    if (!UI_TARGETS.includes(target)) report(`Unknown --ui '${target}' (known: ${UI_TARGETS.join(', ')})`, 1);
+    if (typescript && target !== 'react') report('--typescript applies to --ui react only', 1);
+    if (tokens && !fs.existsSync(tokens)) report(`Design tokens file not found: ${tokens}`, 1);
+
+    let generated;
+    let resolved;
+    let written = null;
+    try {
+      resolved = await resolveCapabilitySource(source);
+      generated = generateUiElements(resolved.manifest, { pluginDir: resolved.stagedDir, target, tokens, typescript });
+      if (out) written = writeUiElements(generated, out, { force });
+    } catch (err) {
+      if (err?.message?.startsWith('process.exit(')) throw err;
+      report(err.message, 1);
+    } finally {
+      resolved?.cleanup?.();
+    }
+
+    if (isJson) {
+      console.log(JSON.stringify({
+        target: generated.target,
+        plugin: generated.pluginId,
+        files: generated.files.map(({ path: p, sha256 }) => ({ path: p, sha256 })),
+        elements: generated.elements,
+        tokens: generated.tokens,
+        warnings: generated.warnings,
+        out: written
+      }));
+    } else {
+      console.log(written
+        ? `✔ Wrote ${generated.files.length} ${generated.target} file(s) for '${generated.pluginId}' to ${written}`
+        : `${generated.target} files for '${generated.pluginId}' (pass --out <dir> to write them):`);
+      for (const f of generated.files) console.log(`  ${f.path}  ${f.sha256.slice(0, 12)}`);
+      console.log(generated.tokens.source
+        ? `  tokens: ${generated.tokens.source === 'app' ? "the app's DESIGN.md" : "the plugin's default DESIGN.md"}`
+        : '  tokens: none — pass --tokens <DESIGN.md> to check required tokens and emit tokens.css');
+      for (const w of generated.warnings) console.log(`  ⚠ ${w}`);
+      console.log(`\nUse it:\n${generated.usage.replace(/^/gm, '  ')}`);
+    }
+    process.exit(0);
+  }
+
+  // 7. APP VERIFY
   else if (sub === 'verify') {
     let target = process.cwd();
     let isJson = false;