total-recall-brain 3.46.2 → 3.47.1

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

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "openwiki",
   "name": "OpenWiki",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Multi-repo knowledge graph and documentation wiki engine for Total Recall.",
   "license": "MIT",
   "runtime": {
@@ -17,10 +17,11 @@
       "command": "watch"
     },
     {
-      "intent": "Auto-refresh OpenWiki documentation for repositories with new commits",
-      "schedule": "*/30 * * * *",
+      "intent": "Refresh OpenWiki documentation nightly for repositories with real code changes, on the selected node",
+      "schedule": "20 1-5 * * *",
       "command": "auto-refresh",
-      "timeout_ms": 600000
+      "timeout_ms": 600000,
+      "placement": "selected-node"
     }
   ],
   "branding": {
@@ -71,7 +72,11 @@
     ]
   },
   "gate": {
-    "tasks": ["Search or read a repository's wiki", "Generate or refresh wiki pages", "Ingest documentation into memory"],
+    "tasks": [
+      "Search or read a repository's wiki",
+      "Generate or refresh wiki pages",
+      "Ingest documentation into memory"
+    ],
     "owned_commands": []
   },
   "cli": {
@@ -84,8 +89,19 @@
         "effect": "read",
         "output": "json",
         "args": [
-          { "name": "task", "label": "Task description", "type": "string", "positional": true, "required": true },
-          { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
+          {
+            "name": "task",
+            "label": "Task description",
+            "type": "string",
+            "positional": true,
+            "required": true
+          },
+          {
+            "name": "json",
+            "label": "JSON output",
+            "type": "boolean",
+            "flag": "--json"
+          }
         ]
       },
       {
@@ -94,11 +110,37 @@
         "effect": "read",
         "output": "json",
         "args": [
-          { "name": "query", "label": "Search terms", "type": "string", "positional": true, "required": true },
-          { "name": "allVaults", "label": "Search all registered vaults", "type": "boolean", "flag": "--all-vaults" },
-          { "name": "node", "label": "Mesh node", "type": "string", "flag": "--node" },
-          { "name": "limit", "label": "Maximum results", "type": "number", "flag": "--limit" },
-          { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
+          {
+            "name": "query",
+            "label": "Search terms",
+            "type": "string",
+            "positional": true,
+            "required": true
+          },
+          {
+            "name": "allVaults",
+            "label": "Search all registered vaults",
+            "type": "boolean",
+            "flag": "--all-vaults"
+          },
+          {
+            "name": "node",
+            "label": "Mesh node",
+            "type": "string",
+            "flag": "--node"
+          },
+          {
+            "name": "limit",
+            "label": "Maximum results",
+            "type": "number",
+            "flag": "--limit"
+          },
+          {
+            "name": "json",
+            "label": "JSON output",
+            "type": "boolean",
+            "flag": "--json"
+          }
         ]
       },
       {
@@ -107,10 +149,35 @@
         "effect": "read",
         "output": "json",
         "args": [
-          { "name": "allVaults", "label": "Inspect all registered vaults", "type": "boolean", "flag": "--all-vaults" },
-          { "name": "node", "label": "Mesh node", "type": "string", "flag": "--node" },
-          { "name": "format", "label": "Graph format", "type": "choice", "options": ["json", "mermaid", "dot"], "flag": "--format" },
-          { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
+          {
+            "name": "allVaults",
+            "label": "Inspect all registered vaults",
+            "type": "boolean",
+            "flag": "--all-vaults"
+          },
+          {
+            "name": "node",
+            "label": "Mesh node",
+            "type": "string",
+            "flag": "--node"
+          },
+          {
+            "name": "format",
+            "label": "Graph format",
+            "type": "choice",
+            "options": [
+              "json",
+              "mermaid",
+              "dot"
+            ],
+            "flag": "--format"
+          },
+          {
+            "name": "json",
+            "label": "JSON output",
+            "type": "boolean",
+            "flag": "--json"
+          }
         ]
       },
       {
@@ -120,11 +187,36 @@
         "output": "json",
         "timeout_ms": 600000,
         "args": [
-          { "name": "repo", "label": "Registered repository", "type": "string", "flag": "--repo" },
-          { "name": "node", "label": "Mesh node", "type": "string", "flag": "--node" },
-          { "name": "force", "label": "Regenerate existing pages", "type": "boolean", "flag": "--force" },
-          { "name": "dryRun", "label": "Describe generation without writing", "type": "boolean", "flag": "--dry-run" },
-          { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
+          {
+            "name": "repo",
+            "label": "Registered repository",
+            "type": "string",
+            "flag": "--repo"
+          },
+          {
+            "name": "node",
+            "label": "Mesh node",
+            "type": "string",
+            "flag": "--node"
+          },
+          {
+            "name": "force",
+            "label": "Regenerate existing pages",
+            "type": "boolean",
+            "flag": "--force"
+          },
+          {
+            "name": "dryRun",
+            "label": "Describe generation without writing",
+            "type": "boolean",
+            "flag": "--dry-run"
+          },
+          {
+            "name": "json",
+            "label": "JSON output",
+            "type": "boolean",
+            "flag": "--json"
+          }
         ]
       },
       {
@@ -133,11 +225,44 @@
         "effect": "write",
         "output": "json",
         "args": [
-          { "name": "action", "label": "Credential action", "type": "choice", "options": ["status", "set"], "positional": true },
-          { "name": "provider", "label": "Credential provider", "type": "choice", "options": ["openrouter", "google"], "positional": true },
-          { "name": "value", "label": "Secret value through stdin", "type": "string", "secret": true },
-          { "name": "stdin", "label": "Read secret from stdin", "type": "boolean", "flag": "--stdin" },
-          { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
+          {
+            "name": "action",
+            "label": "Credential action",
+            "type": "choice",
+            "options": [
+              "status",
+              "set"
+            ],
+            "positional": true
+          },
+          {
+            "name": "provider",
+            "label": "Credential provider",
+            "type": "choice",
+            "options": [
+              "openrouter",
+              "google"
+            ],
+            "positional": true
+          },
+          {
+            "name": "value",
+            "label": "Secret value through stdin",
+            "type": "string",
+            "secret": true
+          },
+          {
+            "name": "stdin",
+            "label": "Read secret from stdin",
+            "type": "boolean",
+            "flag": "--stdin"
+          },
+          {
+            "name": "json",
+            "label": "JSON output",
+            "type": "boolean",
+            "flag": "--json"
+          }
         ]
       },
       {
@@ -146,9 +271,24 @@
         "effect": "read",
         "output": "json",
         "args": [
-          { "name": "allVaults", "label": "Inspect all registered vaults", "type": "boolean", "flag": "--all-vaults" },
-          { "name": "node", "label": "Mesh node", "type": "string", "flag": "--node" },
-          { "name": "json", "label": "JSON output", "type": "boolean", "flag": "--json" }
+          {
+            "name": "allVaults",
+            "label": "Inspect all registered vaults",
+            "type": "boolean",
+            "flag": "--all-vaults"
+          },
+          {
+            "name": "node",
+            "label": "Mesh node",
+            "type": "string",
+            "flag": "--node"
+          },
+          {
+            "name": "json",
+            "label": "JSON output",
+            "type": "boolean",
+            "flag": "--json"
+          }
         ]
       },
       {
@@ -268,7 +408,7 @@
       },
       {
         "name": "refresh",
-        "description": "Report which registered projects' generated OpenWiki pages are stale; --apply regenerates them (openwiki/ only)",
+        "description": "Report which registered projects' generated OpenWiki pages are stale; --apply updates existing wikis (openwiki/ only), never creates one, and skips excluded repositories",
         "timeout_ms": 600000,
         "effect": "write",
         "output": "json",
@@ -291,6 +431,12 @@
             "label": "Force regeneration",
             "type": "boolean"
           },
+          {
+            "name": "budgetMs",
+            "flag": "--budget-ms",
+            "label": "Start no generation that cannot finish within this many milliseconds",
+            "type": "number"
+          },
           {
             "name": "json",
             "flag": "--json",
@@ -422,6 +568,57 @@
             "type": "boolean"
           }
         ]
+      },
+      {
+        "name": "schedule",
+        "description": "Show or choose the node that runs the nightly wiki refresh (task auto-refresh)",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "node",
+            "flag": "--node",
+            "label": "Mesh hostname, or self for this machine",
+            "type": "string"
+          },
+          {
+            "name": "off",
+            "flag": "--off",
+            "label": "Stop the nightly refresh on every node",
+            "type": "boolean"
+          },
+          {
+            "name": "json",
+            "flag": "--json",
+            "label": "JSON output",
+            "type": "boolean"
+          }
+        ]
+      },
+      {
+        "name": "exclude",
+        "description": "List, add or remove repositories the wiki refresh and generate never touch (clones, forks, backups)",
+        "effect": "write",
+        "args": [
+          {
+            "name": "targets",
+            "type": "string",
+            "label": "Registered project name or absolute path",
+            "positional": true
+          },
+          {
+            "name": "remove",
+            "flag": "--remove",
+            "label": "Take the repositories off the list",
+            "type": "boolean"
+          },
+          {
+            "name": "json",
+            "flag": "--json",
+            "label": "JSON output",
+            "type": "boolean"
+          }
+        ]
       }
     ]
   },
@@ -463,5 +660,19 @@
   "status": {
     "command": "status",
     "refresh_seconds": 300
-  }
+  },
+  "reuse": {
+    "commands": [
+      "total-recall auth secret",
+      "total-recall ssss status"
+    ],
+    "owned": "Documentation hub discovery, wiki page auditing, staleness tracking, and OpenWiki knowledge ingestion."
+  },
+  "skills": [
+    {
+      "id": "openwiki",
+      "path": "./skills/openwiki/SKILL.md",
+      "description": "Multi-repo knowledge graph and documentation wiki engine for Total Recall."
+    }
+  ]
 }

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

@@ -0,0 +1,32 @@
+---
+name: openwiki
+description: "Multi-repo knowledge graph and documentation wiki engine for Total Recall."
+version: 0.4.0
+repo_scoped: false
+---
+
+# OpenWiki
+
+Multi-repo knowledge graph and documentation wiki engine for Total Recall.
+
+## When to Use
+
+Use the `openwiki` Total Recall plugin (`total-recall openwiki`) instead of ad-hoc scripts or raw commands whenever working on openwiki tasks.
+
+## Commands
+
+```bash
+total-recall openwiki --help
+total-recall openwiki context  # Retrieve task-relevant wiki and explicitly linked source evidence with provenance and freshness
+total-recall openwiki search  # Search evidence passages in workspace, registered-vault or mesh documentation hubs
+total-recall openwiki graph  # Extract documentation link topology as JSON, Mermaid or DOT
+total-recall openwiki generate  # Generate documentation for the selected registered repository or current workspace
+total-recall openwiki token  # Inspect provider credential status or save a provider key through the shared auth owner
+total-recall openwiki lint  # Inspect documentation links and orphaned hubs without rewriting files
+total-recall openwiki status  # Show which OpenWiki subcommands are implemented
+total-recall openwiki hubs  # List indexed OpenWiki hubs and page counts
+total-recall openwiki ingest  # Ingest markdown documentation into the semantic knowledge graph
+total-recall openwiki bootstrap  # Create missing OpenWiki documentation pages in explicit brain and project directories
+total-recall openwiki probe  # Run HTTP 200 health verification probe
+total-recall openwiki refresh  # Report which registered projects' generated OpenWiki pages are stale; --apply updates existing wikis (openwiki/ only), never creates one, and skips excluded repositories
+```

package/scaffold/.agent/skills/total-recall/plugins/openwiki/src/config.mjs

@@ -6,14 +6,31 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+// No model default: models and prices change too often to fix one in code, and a stale
+// default (deepseek/deepseek-chat) cost about 5x a current model of the same family.
+// A refresh with no configured model stops before it calls a provider.
+//
+// exclude lists repository roots the refresh never touches: upstream clones,
+// forks, backups and test probes. Registering a repository with Total Recall
+// gives it a brain; it does not make its code something to document.
 export const DEFAULT_OPENWIKI_CONFIG = Object.freeze({
   provider: 'openrouter',
-  model: 'deepseek/deepseek-chat',
-  fallback_model: 'deepseek/deepseek-chat',
+  model: null,
+  fallback_model: null,
   max_tokens: 4096,
-  timeout_ms: 300000
+  timeout_ms: 300000,
+  exclude: Object.freeze([])
 });
 
+/** Absolute, de-duplicated, sorted repository roots. */
+export function normalizeExclude(list) {
+  if (!Array.isArray(list)) return [];
+  const roots = list
+    .filter((entry) => typeof entry === 'string' && entry.trim() && path.isAbsolute(entry.trim()))
+    .map((entry) => path.resolve(entry.trim()));
+  return [...new Set(roots)].sort();
+}
+
 export const ALLOWED_CONFIG_KEYS = Object.freeze([
   'provider',
   'model',
@@ -41,12 +58,12 @@ export function loadOpenWikiConfig(options = {}) {
   const filePath = resolveConfigPath(options);
   try {
     if (!fs.existsSync(filePath)) {
-      return { ...DEFAULT_OPENWIKI_CONFIG };
+      return { ...DEFAULT_OPENWIKI_CONFIG, exclude: [] };
     }
     const raw = fs.readFileSync(filePath, 'utf8');
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== 'object') {
-      return { ...DEFAULT_OPENWIKI_CONFIG };
+      return { ...DEFAULT_OPENWIKI_CONFIG, exclude: [] };
     }
     return {
       provider: typeof parsed.provider === 'string' && parsed.provider ? parsed.provider : DEFAULT_OPENWIKI_CONFIG.provider,
@@ -57,10 +74,11 @@ export function loadOpenWikiConfig(options = {}) {
         : DEFAULT_OPENWIKI_CONFIG.max_tokens,
       timeout_ms: Number.isInteger(parsed.timeout_ms) && parsed.timeout_ms >= 30000 && parsed.timeout_ms <= 1800000
         ? parsed.timeout_ms
-        : DEFAULT_OPENWIKI_CONFIG.timeout_ms
+        : DEFAULT_OPENWIKI_CONFIG.timeout_ms,
+      exclude: normalizeExclude(parsed.exclude)
     };
   } catch {
-    return { ...DEFAULT_OPENWIKI_CONFIG };
+    return { ...DEFAULT_OPENWIKI_CONFIG, exclude: [] };
   }
 }
 
@@ -69,18 +87,16 @@ export function saveOpenWikiConfig(config, options = {}) {
   const filePath = resolveConfigPath(options);
   const validated = {
     provider: String(config.provider || DEFAULT_OPENWIKI_CONFIG.provider).toLowerCase(),
-    model: String(config.model || DEFAULT_OPENWIKI_CONFIG.model).trim(),
-    fallback_model: String(config.fallback_model || DEFAULT_OPENWIKI_CONFIG.fallback_model).trim(),
+    model: config.model ? String(config.model).trim() || null : null,
+    fallback_model: config.fallback_model ? String(config.fallback_model).trim() || null : null,
     max_tokens: Number.isInteger(Number(config.max_tokens)) ? Math.max(512, Math.min(131072, Number(config.max_tokens))) : DEFAULT_OPENWIKI_CONFIG.max_tokens,
-    timeout_ms: Number.isInteger(Number(config.timeout_ms)) ? Math.max(30000, Math.min(1800000, Number(config.timeout_ms))) : DEFAULT_OPENWIKI_CONFIG.timeout_ms
+    timeout_ms: Number.isInteger(Number(config.timeout_ms)) ? Math.max(30000, Math.min(1800000, Number(config.timeout_ms))) : DEFAULT_OPENWIKI_CONFIG.timeout_ms,
+    exclude: normalizeExclude(config.exclude)
   };
 
   if (!ALLOWED_PROVIDERS.includes(validated.provider)) {
     throw new Error(`Invalid provider: ${validated.provider}. Allowed: ${ALLOWED_PROVIDERS.join(', ')}`);
   }
-  if (!validated.model) {
-    throw new Error('Model identifier cannot be empty');
-  }
 
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) {
@@ -123,7 +139,17 @@ export function setOpenWikiConfigValue(key, value, options = {}) {
   return saveOpenWikiConfig(current, options);
 }
 
-/** Reset configuration to defaults. */
+/**
+ * Reset the generator settings to defaults. The exclude list is kept: a reset
+ * must not put clones and backups back into a paid refresh.
+ */
 export function resetOpenWikiConfig(options = {}) {
-  return saveOpenWikiConfig(DEFAULT_OPENWIKI_CONFIG, options);
+  const { exclude } = loadOpenWikiConfig(options);
+  return saveOpenWikiConfig({ ...DEFAULT_OPENWIKI_CONFIG, exclude }, options);
+}
+
+/** Replace the list of repository roots the refresh never touches. */
+export function setExcludedRoots(roots, options = {}) {
+  const current = loadOpenWikiConfig(options);
+  return saveOpenWikiConfig({ ...current, exclude: roots }, options);
 }

package/scaffold/.agent/skills/total-recall/plugins/openwiki/src/generate.mjs

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { loadOpenWikiConfig } from './config.mjs';
-import { readProjects, resolveGenerator, resolveKey } from './refresh.mjs';
+import { buildGeneratorInvocation, ensureDefaultIgnores, readProjects, redact, resolveGenerator, resolveKey } from './refresh.mjs';
 import { execOnMeshNode, getMeshNodes } from './mesh-vaults.mjs';
 
 export async function generateWiki({
@@ -70,6 +70,12 @@ export async function generateWiki({
     throw new Error(`Target path does not exist: ${resolvedTarget}`);
   }
 
+  // An excluded repository (an upstream clone, fork, backup or probe) is never
+  // documented, even from inside its own checkout.
+  if ((loadOpenWikiConfig().exclude || []).includes(path.resolve(resolvedTarget))) {
+    throw new Error(`${repoName} is excluded from OpenWiki. To document it, first run: total-recall openwiki exclude --remove ${repoName}`);
+  }
+
   const outPath = outputDir ? path.resolve(resolvedTarget, outputDir) : path.join(resolvedTarget, 'openwiki');
 
   if (dryRun) {
@@ -92,31 +98,30 @@ export async function generateWiki({
   }
 
   const gen = resolveGenerator();
-  const generatorArgs = [...gen.args];
-
-  // Pass --init or update mode
-  const isInit = !fs.existsSync(outPath) || force;
-  if (isInit) {
-    generatorArgs.push('--init');
+  if (!gen.command) {
+    throw new Error('No openwiki generator available (missing bundled generator, local .bin, PATH entry, or npx)');
   }
 
-  const env = {
-    ...process.env,
-    OPENROUTER_API_KEY: config.provider === 'openrouter' ? key : process.env.OPENROUTER_API_KEY,
-    GOOGLE_API_KEY: config.provider === 'google' ? key : process.env.GOOGLE_API_KEY,
-    OPENWIKI_MODEL: config.model,
-    OPENWIKI_TIMEOUT: String(config.timeout_ms || 300000),
-  };
+  const mode = (!fs.existsSync(outPath) || force) ? 'init' : 'update';
+  const timeoutMs = config.timeout_ms || 300000;
+  const { cmdArgs, childEnv } = buildGeneratorInvocation({
+    baseArgs: gen.args,
+    mode,
+    config,
+    key,
+  });
+  ensureDefaultIgnores(resolvedTarget);
 
   const startedAt = Date.now();
   if (typeof onProgress === 'function') {
-    onProgress(`Starting generator for ${repoName} (${gen.via})...`);
+    onProgress(`Starting generator for ${repoName} (${gen.via}, ${mode})...`);
   }
 
   return new Promise((resolve, reject) => {
-    const child = spawn(gen.command, generatorArgs, {
+    const child = spawn(gen.command, cmdArgs, {
       cwd: resolvedTarget,
-      env,
+      env: childEnv,
+      timeout: timeoutMs,
       stdio: ['ignore', 'pipe', 'pipe'],
     });
 
@@ -127,7 +132,7 @@ export async function generateWiki({
       const str = chunk.toString();
       stdout += str;
       if (typeof onProgress === 'function') {
-        onProgress(str.trim());
+        onProgress(redact(str.trim(), key));
       }
     });
 
@@ -135,7 +140,7 @@ export async function generateWiki({
       stderr += chunk.toString();
     });
 
-    child.on('close', (code) => {
+    child.on('close', (code, signal) => {
       const durationMs = Date.now() - startedAt;
       if (code === 0) {
         resolve({
@@ -144,17 +149,19 @@ export async function generateWiki({
           targetPath: resolvedTarget,
           outputDir: outPath,
           generatorVia: gen.via,
+          mode,
           durationMs,
           credential: from,
-          stdout: stdout.trim(),
+          stdout: redact(stdout.trim(), key),
         });
       } else {
-        reject(new Error(`Generator exited with code ${code}: ${stderr || stdout || 'Unknown error'}`));
+        const detail = redact(stderr || stdout || (signal ? `terminated by ${signal}` : 'Unknown error'), key);
+        reject(new Error(`Generator exited with code ${code ?? signal ?? 1}: ${detail}`));
       }
     });
 
     child.on('error', (err) => {
-      reject(new Error(`Failed to spawn generator: ${err.message}`));
+      reject(new Error(`Failed to spawn generator: ${redact(err.message, key)}`));
     });
   });
 }