total-recall-brain 3.44.0 → 3.46.0

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

@@ -30,6 +30,19 @@ const PLUGIN_ROOT = fileURLToPath(new URL('..', import.meta.url));
 const RETENTION_NOTE = 'pages are a projection, not canonical memory';
 const DEFAULT_LOCK_MS = 6 * 60 * 60 * 1000;
 
+const gitRun = (_command, args, options) => spawnSync('total-recall', ['git', ...args], options);
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+/** An unfinished init must resume as init, even after it has written pages. */
+export function generationMode(root) {
+  const state = readJson(path.join(root, 'openwiki', '.run.json'));
+  if (state?.mode === 'init' && state.phase && !['complete', 'idle'].includes(state.phase)) return 'init';
+  return hasWiki(root) ? 'update' : 'init';
+}
+
 export function registryPath(home = os.homedir()) {
   return path.join(home, '.agent', 'skills', 'total-recall', 'config', 'project-registry.json');
 }
@@ -69,7 +82,7 @@ export function readProjects({ registry = registryPath() } = {}) {
   });
 }
 
-/** Does this project carry generated pages at all? A repo with no openwiki/ is skipped, never created. */
+/** Does this project carry generated Markdown pages? */
 export function hasWiki(root) {
   const dir = path.join(root, 'openwiki');
   const stat = fs.lstatSync(dir, { throwIfNoEntry: false });
@@ -82,15 +95,18 @@ export function hasWiki(root) {
  * since the recorded generation, which is the same measure the per-repo driver
  * used. Uncommitted work is not counted, so an open edit does not read as drift.
  */
-export function isGitRepo(root, { git = spawnSync } = {}) {
+export function isGitRepo(root, { git = gitRun } = {}) {
   if (fs.existsSync(path.join(root, '.git'))) return true;
   const res = git('git', ['-C', root, 'rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' });
-  return !res.error && res.status === 0;
+  if (res.error || res.status !== 0 || String(res.stdout).trim() !== 'true') return false;
+  const top = git('git', ['-C', root, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+  if (top.error || top.status !== 0) return false;
+  return fs.realpathSync(root) === fs.realpathSync(String(top.stdout).trim());
 }
 
-export function staleness(root, { git = spawnSync } = {}) {
+export function staleness(root, { git = gitRun } = {}) {
   if (!isGitRepo(root, { git })) {
-    return { root, head: '', generatedAt: null, generatedStatus: null, files: null, lastCodeChange: null, commitsSince: 0, stale: false };
+    return { root, head: '', generationCommit: null, generationTime: null, generatedAt: null, generatedStatus: null, files: null, lastCodeChange: null, commitsSince: 0, stale: false };
   }
   const marker = path.join(root, 'openwiki', '.last-update.json');
   let head = '';
@@ -104,6 +120,11 @@ export function staleness(root, { git = spawnSync } = {}) {
     generatedAt = typeof parsed.updatedAt === 'string' ? parsed.updatedAt : null;
     generatedStatus = typeof parsed.status === 'string' ? parsed.status : null;
   } catch { /* no marker: never generated, or unreadable */ }
+  const receipt = readJson(path.join(root, 'openwiki', '.generation.json'));
+  const validReceipt = typeof receipt?.commit === 'string' && /^[a-f0-9]{7,64}$/i.test(receipt.commit)
+    && typeof receipt.completedAt === 'string' && Number.isFinite(Date.parse(receipt.completedAt));
+  const generationCommit = validReceipt ? receipt.commit : null;
+  const generationTime = validReceipt ? receipt.completedAt : null;
 
   // The page contents, so a refresh can be judged on what it actually rewrote.
   // openwiki writes its marker when generation begins, so the marker alone
@@ -122,12 +143,15 @@ export function staleness(root, { git = spawnSync } = {}) {
   const lastCodeChange = !log.error && log.status === 0 ? String(log.stdout || '').trim() || null : null;
 
   let commitsSince = null;
-  if (generatedAt) {
-    const count = git('git', ['-C', root, 'rev-list', '--count', `--since=${generatedAt}`, 'HEAD', '--', '.', ':!openwiki'], { encoding: 'utf8' });
-    if (!count.error && count.status === 0) commitsSince = Number(String(count.stdout || '').trim());
-  }
-  const stale = generatedAt === null || (Number.isFinite(commitsSince) && commitsSince > 0);
-  return { root, head, generatedAt, generatedStatus, files, lastCodeChange, commitsSince, stale };
+  if (generationCommit || generatedAt) {
+    const range = generationCommit ? [`${generationCommit}..HEAD`] : [`--since=${generatedAt}`, 'HEAD'];
+    const count = git('git', ['-C', root, 'rev-list', '--count', ...range, '--', '.', ':!openwiki'], { encoding: 'utf8' });
+    const value = String(count.stdout || '').trim();
+    if (!count.error && count.status === 0 && /^\d+$/.test(value)) commitsSince = Number(value);
+  }
+  const incomplete = generatedStatus === 'interrupted' || stillGenerating(root);
+  const stale = incomplete || generatedAt === null || commitsSince === null || commitsSince > 0;
+  return { root, head, generationCommit, generationTime, generatedAt, generatedStatus, files, lastCodeChange, commitsSince, stale, mode: generationMode(root) };
 }
 
 /**
@@ -250,14 +274,84 @@ export function stillGenerating(root) {
   }
 }
 
+function writeReceipt(root, name, value) {
+  const dir = path.join(root, 'openwiki');
+  fs.mkdirSync(dir, { recursive: true });
+  const target = path.join(dir, name);
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    fs.renameSync(tmp, target);
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+function redact(value, key) {
+  let text = String(value || '');
+  if (key) text = text.split(key).join('[REDACTED]');
+  return text.replace(/\bBearer\s+\S+/gi, 'Bearer [REDACTED]').replace(/\bsk-[\w-]+/g, '[REDACTED]');
+}
+
+function finishRefresh(project, { before, result, git, key, mode, startedAt, via, clock }) {
+  const after = staleness(project.root, { git });
+  const exitCode = result.error ? (result.error.code || 1) : result.signal ? 1 : result.status;
+  const completedAt = new Date(clock()).toISOString();
+  const stdout = redact(result.stdout, key), stderr = redact(result.stderr, key);
+  const error = redact(result.error?.message, key);
+  const clean = text => String(text || '').replace(/\x1b\[[0-9;]*m/g, '').split(/\r?\n/)
+    .map(line => line.trim().replace(/^\[ERR\]\s*/, '')).filter(line => line && line !== 'Error Diagnostics');
+  const errLines = clean(stderr), outLines = clean(stdout);
+  const diagnostic = [...errLines, ...outLines].find(line => /context_length_exceeded|Provider returned error|exited without|Could not restore|interrupted OpenWiki|fetch failed/.test(line));
+  // The generator's own first error line names the cause; a trailing "Status: 400" does not.
+  const reason = error || (result.signal ? `generator stopped by ${result.signal}` : diagnostic || errLines[0] || outLines.at(-1) || `exit ${exitCode}`);
+  const wrote = pagesWritten(before, after) || (!before.files && hasWiki(project.root) ? 1 : 0);
+  const advanced = after.generatedAt !== before.generatedAt;
+  let action, failureReason;
+  if (after.generatedStatus === 'interrupted' || stillGenerating(project.root)) {
+    action = 'partial';
+    failureReason = `${wrote} page(s) rewritten, but the run did not finish; it resumes on the next refresh (${reason})`;
+  } else if (exitCode !== 0) {
+    action = 'failed'; failureReason = reason;
+  } else if (!advanced && !wrote) {
+    action = 'failed'; failureReason = 'command exited 0 and no page changed';
+  } else if (!before.head) {
+    action = 'failed'; failureReason = 'Cannot record generation without a source commit';
+  } else {
+    action = mode === 'init' ? 'initialized' : 'refreshed';
+  }
+  const logPath = path.join(project.root, 'openwiki', '.refresh-attempt.json');
+  const report = { ...project, ...after, action, reason: failureReason, exitCode, signal: result.signal || null, from: before.generatedAt, to: after.generatedAt, durationMs: clock() - startedAt, via, mode, logPath };
+  try {
+    writeReceipt(project.root, '.refresh-attempt.json', { startedAt: new Date(startedAt).toISOString(), completedAt, sourceCommit: before.head || null, action, mode, exitCode, signal: result.signal || null, error, stdout, stderr });
+    if (action === 'initialized' || action === 'refreshed') {
+      writeReceipt(project.root, '.generation.json', { commit: before.head, completedAt });
+      report.generationCommit = before.head;
+      report.generationTime = completedAt;
+      report.commitsSince = after.head === before.head ? 0 : null;
+      report.stale = after.head !== before.head;
+    } else if (before.generationCommit && before.generationTime) {
+      // Init can replace openwiki/ before it fails. Retain the last success.
+      writeReceipt(project.root, '.generation.json', { commit: before.generationCommit, completedAt: before.generationTime });
+      report.generationCommit = before.generationCommit;
+      report.generationTime = before.generationTime;
+    }
+  } catch (error) {
+    report.action = 'failed'; report.reason = `Could not save refresh receipt: ${error.message}`;
+  }
+  return report;
+}
+
 export function refreshProject(project, {
-  key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, run = spawnSync, now = Date.now(), targetVersion = null, pluginRoot = PLUGIN_ROOT,
+  key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, run = spawnSync, now = Date.now(), clock = Date.now, targetVersion = null, pluginRoot = PLUGIN_ROOT,
 } = {}) {
-  if (!isGitRepo(project.root, { git: run })) {
+  const git = run === spawnSync ? gitRun : run;
+  if (!isGitRepo(project.root, { git })) {
     return { ...project, action: 'skipped', reason: 'not a git repository' };
   }
-  const before = staleness(project.root, { git: run });
+  const before = staleness(project.root, { git });
   const uninitialized = !hasWiki(project.root);
+  const mode = generationMode(project.root);
 
   let command = binary, args = binaryArgs, via = binary ? 'explicit' : null;
   if (!command) {
@@ -273,19 +367,12 @@ export function refreshProject(project, {
   const selectedModel = model || config.model;
   const selectedProvider = provider || config.provider;
 
-  const modeFlag = uninitialized ? '--init' : '--update';
+  const modeFlag = `--${mode}`;
   const cmdArgs = [...args, modeFlag, '-p'];
   if (selectedModel) {
     cmdArgs.push('--modelId', selectedModel);
   }
 
-  if (uninitialized) {
-    const runFile = path.join(project.root, 'openwiki', '.run.json');
-    if (fs.existsSync(runFile)) {
-      try { fs.unlinkSync(runFile); } catch {}
-    }
-  }
-
   const childEnv = { ...process.env };
   if (selectedProvider === 'google') {
     childEnv.GOOGLE_API_KEY = key;
@@ -312,47 +399,18 @@ export function refreshProject(project, {
     timeout: timeoutMs,
   });
 
-  const after = staleness(project.root, { git: run });
-  const exitCode = result.error ? (result.error.code || 1) : result.status;
-  const advanced = after.generatedAt !== before.generatedAt || (uninitialized && hasWiki(project.root));
-  const wrote = pagesWritten(before, after) || (uninitialized && hasWiki(project.root) ? 1 : 0);
-
-  const outcome = after.generatedStatus === 'interrupted' || stillGenerating(project.root)
-    ? 'partial'
-    : (advanced ? (uninitialized ? 'initialized' : 'refreshed') : 'unchanged');
-
-  if (exitCode !== 0 && !wrote) {
-    return { ...project, action: 'failed', reason: result.error?.message || `exit ${exitCode}`, exitCode, ...after };
-  }
-  if (!advanced && !wrote) {
-    return { ...project, action: 'failed', reason: `command exited ${exitCode} and no page changed`, exitCode, ...after };
-  }
-  if (outcome === 'partial') {
-    return {
-      ...project,
-      action: 'partial',
-      reason: `${wrote} page(s) rewritten, but the run did not finish (the generator was cut off); it resumes on the next refresh`,
-      exitCode,
-      from: before.generatedAt,
-      to: after.generatedAt,
-      via,
-      ...after,
-    };
-  }
-  if (exitCode !== 0) {
-    return { ...project, action: 'failed', reason: result.error?.message || `exit ${exitCode}`, exitCode, ...after };
-  }
-  return { ...project, action: uninitialized ? 'initialized' : 'refreshed', from: before.generatedAt, to: after.generatedAt, durationMs: Date.now() - startedAt, via, ...after };
+  return finishRefresh(project, { before, result, git, key, mode, startedAt, via, clock });
 }
 
 export async function refreshProjectAsync(project, {
-  key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, now = Date.now(), targetVersion = null, pluginRoot = PLUGIN_ROOT,
+  key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, now = Date.now(), clock = Date.now, targetVersion = null, pluginRoot = PLUGIN_ROOT, git = gitRun, spawnProcess = spawn,
 } = {}) {
-  if (!isGitRepo(project.root, { git: spawnSync })) {
+  if (!isGitRepo(project.root, { git })) {
     return { ...project, action: 'skipped', reason: 'not a git repository' };
   }
-  const before = staleness(project.root, { git: spawnSync });
+  const before = staleness(project.root, { git });
   const uninitialized = !hasWiki(project.root);
+  const mode = generationMode(project.root);
   let command = binary, args = binaryArgs, via = binary ? 'explicit' : null;
   if (!command) {
     const resolved = resolveGenerator({ run: spawnSync, targetVersion, pluginRoot, requireBundled: uninitialized });
@@ -367,19 +425,12 @@ export async function refreshProjectAsync(project, {
   const selectedModel = model || config.model;
   const selectedProvider = provider || config.provider;
 
-  const modeFlag = uninitialized ? '--init' : '--update';
+  const modeFlag = `--${mode}`;
   const cmdArgs = [...args, modeFlag, '-p'];
   if (selectedModel) {
     cmdArgs.push('--modelId', selectedModel);
   }
 
-  if (uninitialized) {
-    const runFile = path.join(project.root, 'openwiki', '.run.json');
-    if (fs.existsSync(runFile)) {
-      try { fs.unlinkSync(runFile); } catch {}
-    }
-  }
-
   const childEnv = { ...process.env };
   if (selectedProvider === 'google') {
     childEnv.GOOGLE_API_KEY = key;
@@ -399,74 +450,33 @@ export async function refreshProjectAsync(project, {
 
   const startedAt = now;
   const result = await new Promise((resolve) => {
-    const proc = spawn(command, cmdArgs, {
+    const proc = spawnProcess(command, cmdArgs, {
       cwd: project.root,
       env: childEnv,
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: timeoutMs,
     });
-    let stdout = '', stderr = '';
+    let stdout = '', stderr = '', error = null;
     proc.stdout?.on('data', (d) => { stdout += d; });
     proc.stderr?.on('data', (d) => { stderr += d; });
-    proc.on('error', (err) => resolve({ error: err, status: 1, stdout, stderr }));
-    proc.on('close', (status) => resolve({ status: status ?? 0, stdout, stderr }));
+    proc.on('error', (err) => { error = err; });
+    proc.on('close', (status, signal) => resolve({ error, status, signal, stdout, stderr }));
   });
-
-  const after = staleness(project.root, { git: spawnSync });
-  const exitCode = result.error ? (result.error.code || 1) : result.status;
-  const advanced = after.generatedAt !== before.generatedAt || (uninitialized && hasWiki(project.root));
-  const wrote = pagesWritten(before, after) || (uninitialized && hasWiki(project.root) ? 1 : 0);
-
-  const outcome = after.generatedStatus === 'interrupted' || stillGenerating(project.root)
-    ? 'partial'
-    : (advanced ? (uninitialized ? 'initialized' : 'refreshed') : 'unchanged');
-
-  const extractReason = (rawErr, rawOut) => {
-    if (result.error?.message) return result.error.message;
-    const combined = `${rawErr || ''}\n${rawOut || ''}`.trim();
-    if (!combined) return `exit ${exitCode}`;
-    const lines = combined.split('\n').map((l) => l.trim()).filter(Boolean);
-    const diag = lines.find((l) => l.includes('Error Diagnostics') || l.includes('exited without') || l.includes('Could not restore') || l.includes('Provider returned error') || l.includes('fetch failed'));
-    if (diag) return diag.replace(/^\[ERR\]\s*/, '');
-    const last = lines[lines.length - 1];
-    return last ? last.replace(/^\[ERR\]\s*/, '') : `exit ${exitCode}`;
-  };
-  const failReason = extractReason(result.stderr, result.stdout);
-
-  if (exitCode !== 0 && !wrote) {
-    return { ...project, action: 'failed', reason: failReason, exitCode, ...after };
-  }
-  if (!advanced && !wrote) {
-    return { ...project, action: 'failed', reason: failReason || `command exited ${exitCode} and no page changed`, exitCode, ...after };
-  }
-  if (outcome === 'partial') {
-    return {
-      ...project,
-      action: 'partial',
-      reason: `${wrote} page(s) rewritten, but the run did not finish (the generator was cut off); it resumes on the next refresh`,
-      exitCode,
-      from: before.generatedAt,
-      to: after.generatedAt,
-      via,
-      ...after,
-    };
-  }
-  if (exitCode !== 0) {
-    return { ...project, action: 'failed', reason: failReason, exitCode, ...after };
-  }
-  return { ...project, action: uninitialized ? 'initialized' : 'refreshed', from: before.generatedAt, to: after.generatedAt, durationMs: Date.now() - startedAt, via, ...after };
+  return finishRefresh(project, { before, result, git, key, mode, startedAt, via, clock });
 }
 
 /** Is a refresh due for this project under the configured interval? */
-export function isDue(project, { lockMs = DEFAULT_LOCK_MS, now = Date.now(), git = spawnSync } = {}) {
+export function isDue(project, { lockMs = DEFAULT_LOCK_MS, now = Date.now(), git = gitRun, force = false } = {}) {
   if (!isGitRepo(project.root, { git })) {
     return { due: false, skipped: true, reason: 'not a git repository' };
   }
   const state = staleness(project.root, { git });
+  if (force) return { due: true, uninitialized: !hasWiki(project.root), ...state };
   if (!hasWiki(project.root)) {
     return { due: true, uninitialized: true, reason: 'uninitialized (missing openwiki/ pages)', ...state };
   }
   if (!state.stale) return { due: false, ...state };
+  if (state.generatedStatus === 'interrupted' || stillGenerating(project.root)) return { due: true, reason: 'resume incomplete generation', ...state };
   if (state.generatedAt) {
     const at = Date.parse(state.generatedAt);
     if (Number.isFinite(at) && now - at < lockMs) return { due: false, reason: 'refreshed recently', ...state };

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

@@ -36,11 +36,9 @@ export async function searchWikiHubs(query, {
 
   // If remote mesh node specified, dispatch via mesh
   if (node && node !== 'local' && node !== 'self') {
-    const escapedQuery = query.replace(/"/g, '\\"');
-    const meshRes = execOnMeshNode(
-      node,
-      `total-recall openwiki search "${escapedQuery}" ${allVaults ? '--all-vaults' : ''} --json`
-    );
+    const meshRes = execOnMeshNode(node, [
+      'search', query, ...(allVaults ? ['--all-vaults'] : []), '--limit', String(limit), '--json',
+    ]);
     if (meshRes.ok) {
       try {
         return JSON.parse(meshRes.stdout);

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

@@ -15,60 +15,34 @@ const PROVIDER_KEY_MAP = {
 /**
  * Checks token readiness across supported providers.
  */
-export function getTokenStatus() {
-  const result = spawnSync('total-recall', ['auth', 'secret', 'list', '--json'], {
+export function getTokenStatus({ run = spawnSync } = {}) {
+  const result = run('total-recall', ['auth', 'secret', 'list', '--json'], {
     encoding: 'utf8',
     timeout: 5000,
   });
 
-  const configured = {
-    openrouter: false,
-    google: false,
-  };
-
-  if (result.status === 0 && result.stdout) {
-    try {
-      const parsed = JSON.parse(result.stdout);
-      const keys = Array.isArray(parsed)
-        ? parsed.map((k) => (typeof k === 'string' ? k : k.key || k.name))
-        : (parsed.keys || []);
-
-      configured.openrouter = keys.includes('OPENROUTER_API_KEY') || Boolean(process.env.OPENROUTER_API_KEY);
-      configured.google = keys.includes('GOOGLE_API_KEY') || Boolean(process.env.GOOGLE_API_KEY);
-    } catch {
-      configured.openrouter = Boolean(process.env.OPENROUTER_API_KEY);
-      configured.google = Boolean(process.env.GOOGLE_API_KEY);
-    }
-  } else {
-    configured.openrouter = Boolean(process.env.OPENROUTER_API_KEY);
-    configured.google = Boolean(process.env.GOOGLE_API_KEY);
-  }
-
-  return {
-    ok: true,
-    tokens: {
-      openrouter: {
-        key: 'OPENROUTER_API_KEY',
-        configured: configured.openrouter,
-        status: configured.openrouter ? 'configured' : 'missing',
-      },
-      google: {
-        key: 'GOOGLE_API_KEY',
-        configured: configured.google,
-        status: configured.google ? 'configured' : 'missing',
-      },
-    },
-  };
+  if (result.status !== 0) throw new Error('Auth credential metadata is unavailable');
+  let payload;
+  try { payload = JSON.parse(result.stdout); }
+  catch { throw new Error('Auth credential metadata is invalid'); }
+  const rows = Array.isArray(payload) ? payload : payload?.keys;
+  if (!Array.isArray(rows)) throw new Error('Auth credential metadata is invalid');
+  const saved = new Set(rows.filter(row => row?.set !== false)
+    .map(row => typeof row === 'string' ? row : row?.key ?? row?.name));
+  const tokens = Object.fromEntries(Object.entries(PROVIDER_KEY_MAP).map(([provider, key]) => {
+    const configured = saved.has(key);
+    return [provider, { key, configured, status: configured ? 'configured' : 'missing' }];
+  }));
+  return { ok: true, tokens };
 }
 
 /**
  * Securely writes a token into Total Recall auth secrets store using --stdin.
  */
-export function setTokenValue(provider, secretValue) {
-  const keyName = PROVIDER_KEY_MAP[provider?.toLowerCase()] || provider;
-  if (!keyName) {
-    throw new Error(`Unsupported token provider '${provider}'. Allowed: openrouter, google`);
-  }
+export function setTokenValue(provider, secretValue, { run = spawnSync } = {}) {
+  const id = typeof provider === 'string' && provider.toLowerCase();
+  if (!Object.hasOwn(PROVIDER_KEY_MAP, id)) throw new Error('Supported token providers are openrouter and google');
+  const keyName = PROVIDER_KEY_MAP[id];
 
   if (!secretValue || typeof secretValue !== 'string' || !secretValue.trim()) {
     throw new Error(`Token value for ${keyName} must be a non-empty string`);
@@ -77,14 +51,14 @@ export function setTokenValue(provider, secretValue) {
   const trimmed = secretValue.trim();
 
   // Pipe into total-recall auth secret set <KEY> --stdin
-  const child = spawnSync('total-recall', ['auth', 'secret', 'set', keyName, '--stdin'], {
+  const child = run('total-recall', ['auth', 'secret', 'set', keyName, '--stdin'], {
     input: trimmed,
     encoding: 'utf8',
     timeout: 5000,
   });
 
   if (child.status !== 0) {
-    throw new Error(child.stderr || child.error?.message || `Failed to set ${keyName} in secrets store`);
+    throw new Error(`Auth could not save ${keyName}`);
   }
 
   return {

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

@@ -15,6 +15,15 @@ import { hasWiki, readProjects, refreshProject, resolveKey } from './refresh.mjs
 export const UPSTREAM_NPM_URL = 'https://registry.npmjs.org/openwiki/latest';
 export const UPSTREAM_GITHUB_URL = 'https://api.github.com/repos/langchain-ai/openwiki/releases/latest';
 
+export function bundledGeneratorVersion() {
+  try {
+    if (!fs.existsSync(new URL('../vendor/openwiki.mjs', import.meta.url))) return null;
+    const build = JSON.parse(fs.readFileSync(new URL('../vendor/build.json', import.meta.url), 'utf8'));
+    return typeof build.version === 'string' && /^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.-]+)?$/.test(build.version)
+      ? build.version : null;
+  } catch { return null; }
+}
+
 /**
  * Resolves the path to the persistent upstream state file.
  * @param {string} [home] Home directory override
@@ -34,20 +43,21 @@ export function stateFile(home = os.homedir()) {
  * @returns {{ currentRecordedVersion: string, latestKnownVersion: string, lastCheckedAt: string | null, announcements: Array<object> }}
  */
 export function readUpstreamState({ statePath = stateFile() } = {}) {
+  const baseline = bundledGeneratorVersion() || '0.0.0';
   try {
     const raw = fs.readFileSync(statePath, 'utf8');
     const parsed = JSON.parse(raw);
     return {
-      currentRecordedVersion: typeof parsed.currentRecordedVersion === 'string' ? parsed.currentRecordedVersion : '0.7.2',
-      latestKnownVersion: typeof parsed.latestKnownVersion === 'string' ? parsed.latestKnownVersion : '0.7.2',
+      currentRecordedVersion: typeof parsed.currentRecordedVersion === 'string' ? parsed.currentRecordedVersion : baseline,
+      latestKnownVersion: typeof parsed.latestKnownVersion === 'string' ? parsed.latestKnownVersion : baseline,
       lastCheckedAt: typeof parsed.lastCheckedAt === 'string' ? parsed.lastCheckedAt : null,
       lastPropagatedAt: typeof parsed.lastPropagatedAt === 'string' ? parsed.lastPropagatedAt : null,
       announcements: Array.isArray(parsed.announcements) ? parsed.announcements : []
     };
   } catch {
     return {
-      currentRecordedVersion: '0.7.2',
-      latestKnownVersion: '0.7.2',
+      currentRecordedVersion: baseline,
+      latestKnownVersion: baseline,
       lastCheckedAt: null,
       lastPropagatedAt: null,
       announcements: []
@@ -62,13 +72,14 @@ export function readUpstreamState({ statePath = stateFile() } = {}) {
  * @param {string} [options.statePath] Custom state path
  */
 export function saveUpstreamState(state = {}, { statePath = stateFile() } = {}) {
+  const baseline = bundledGeneratorVersion() || '0.0.0';
   const dir = path.dirname(statePath);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
   const payload = {
-    currentRecordedVersion: state.currentRecordedVersion || '0.7.2',
-    latestKnownVersion: state.latestKnownVersion || '0.7.2',
+    currentRecordedVersion: state.currentRecordedVersion || baseline,
+    latestKnownVersion: state.latestKnownVersion || baseline,
     lastCheckedAt: state.lastCheckedAt || new Date().toISOString(),
     lastPropagatedAt: state.lastPropagatedAt || null,
     announcements: Array.isArray(state.announcements) ? state.announcements.slice(-20) : []

package/scaffold/.agent/skills/total-recall/plugins/openwiki/ui/chunks/auto-refresh.md

@@ -0,0 +1,18 @@
+---
+type: ui-chunk:chunk
+plugin: openwiki
+id: auto-refresh
+title: Scheduled wiki refresh
+description: Understand the daemon operation that applies regeneration to due registered repositories.
+timestamp: "2026-11-08T09:14:38Z"
+intents: [inspect scheduled wiki refresh, understand automatic regeneration, review daemon wiki refresh]
+surfaces: [page]
+operations: [auto-refresh]
+data: ["auto-refresh:/counts/current", "auto-refresh:/counts/refreshed"]
+---
+
+<section style="border-inline-start:3px solid var(--color-primary,#8d3e10);padding-inline-start:1rem">
+  <h2>Scheduled wiki refresh</h2>
+  <p><code>auto-refresh</code> is the daemon's applying operation. It checks the selected registered repositories and regenerates due pages.</p>
+  <p>Use <code>total-recall openwiki refresh --json</code> for an operator preview. Review the scheduled run receipt to see what the daemon refreshed.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/openwiki/ui/chunks/bootstrap-pages.md

@@ -0,0 +1,18 @@
+---
+type: ui-chunk:chunk
+plugin: openwiki
+id: bootstrap-pages
+title: Seed missing wiki pages
+description: Preview which owner-provided pages would be created in an explicit brain or project.
+timestamp: "2026-11-08T09:14:38Z"
+intents: [bootstrap wiki pages, seed repository documentation, review missing starter pages]
+surfaces: [page]
+operations: [bootstrap]
+data: ["bootstrap:/files_planned", "bootstrap:/files_preserved"]
+---
+
+<section>
+  <h2>Seed missing wiki pages</h2>
+  <p>Choose an absolute brain path and, optionally, a project root. Run <code>total-recall openwiki bootstrap --brain &lt;path&gt; --dry-run --json</code> to see the planned pages.</p>
+  <p>Review the target paths before applying. The bootstrap receipt separates new pages from existing files that it preserved.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/openwiki/ui/chunks/generate-wiki.md

@@ -0,0 +1,21 @@
+---
+type: ui-chunk:chunk
+plugin: openwiki
+id: generate-wiki
+title: Preview wiki generation
+description: Inspect the selected repository and output location before generating documentation.
+timestamp: "2026-11-08T09:14:38Z"
+intents: [preview wiki generation, generate repo documentation, inspect generation destination]
+surfaces: [page]
+operations: [generate]
+data: ["generate:/ok", "generate:/dryRun"]
+---
+
+<section>
+  <h2>Preview wiki generation</h2>
+  <ol>
+    <li>Run <code>total-recall openwiki generate --dry-run --json</code> for the current workspace, or select a registered repository with <code>--repo</code>.</li>
+    <li>Review the selected repository and wiki output directory.</li>
+    <li>Start generation after approving the target and configured provider.</li>
+  </ol>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/openwiki/ui/chunks/generator-settings.md

@@ -0,0 +1,18 @@
+---
+type: ui-chunk:chunk
+plugin: openwiki
+id: generator-settings
+title: Inspect generator configuration
+description: Review the configured provider, model routing, token bound and timeout.
+timestamp: "2026-11-08T09:14:38Z"
+intents: [inspect OpenWiki configuration, review generation limits, change wiki generator settings]
+surfaces: [page, right]
+operations: [config]
+data: ["config:/config/provider", "config:/config/max_tokens", "config:/config/timeout_ms"]
+---
+
+<section>
+  <h2>Inspect generator configuration</h2>
+  <p>Run <code>total-recall openwiki config show --json</code> to inspect the active provider, routing, token bound and timeout.</p>
+  <p>Use <code>config get</code> for an individual setting. An explicit <code>config set</code> changes the chosen setting for future generation.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/openwiki/ui/chunks/host-probe.md

@@ -0,0 +1,18 @@
+---
+type: ui-chunk:chunk
+plugin: openwiki
+id: host-probe
+title: Probe the Total Recall host
+description: Check the configured host's health endpoint and observe response latency.
+timestamp: "2026-11-08T09:14:38Z"
+intents: [probe Total Recall host, inspect wiki host availability, check health response]
+surfaces: [page, right]
+operations: [probe]
+data: ["probe:/ok", "probe:/status", "probe:/latency_ms"]
+---
+
+<section>
+  <h2>Probe the Total Recall host</h2>
+  <p>Run <code>total-recall openwiki probe --json</code> to observe the HTTP status and response time for the configured host's health endpoint.</p>
+  <p>Use the wiki index or evidence search to check documentation coverage.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/openwiki/ui/chunks/ingest-preview.md

@@ -0,0 +1,18 @@
+---
+type: ui-chunk:chunk
+plugin: openwiki
+id: ingest-preview
+title: Preview wiki ingestion
+description: Count pages selected for import into the requested Total Recall brain.
+timestamp: "2026-11-08T09:14:38Z"
+intents: [preview wiki ingest, import markdown into project brain, inspect wiki import receipt]
+surfaces: [page]
+operations: [ingest]
+data: ["ingest:/planned", "ingest:/imported", "ingest:/errors"]
+---
+
+<section>
+  <h2>Preview wiki ingestion</h2>
+  <p>Run <code>total-recall openwiki ingest &lt;directory&gt; --project --dry-run --json</code> to count pages planned for the project brain. Select <code>--global</code> only when the shared brain is the intended target.</p>
+  <p>After approving the target, run the import and review the completed and failed counts. Confirm indexed passages through Total Recall recall.</p>
+</section>