total-recall-brain 3.41.1 → 3.41.3

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

@@ -14,8 +14,19 @@ Peers install it with `npx total-recall plugin install peer:<this-node>/openwiki
 
 ## Features
 
+OpenWiki owns documentation bootstrap and templates. Total Recall core initializes portable memory without creating OpenWiki pages. After installing this plugin, create missing documentation explicitly:
+
+```sh
+total-recall openwiki bootstrap --brain /absolute/path/to/brain \
+  --project-root /absolute/path/to/repository --json
+```
+
+`--brain` is required. `--project-root` adds repository documentation; omit it to seed only the brain's `openwiki/` directory. Existing files and page symlinks are preserved. A symlinked destination directory or a non-file page fails explicitly. `--dry-run` reports planned pages without writing. Bootstrap is a local Node-only operation and does not require credentials, a Total Recall server, ingestion or a provider request.
+
+`total-recall openwiki hubs --json` lists repository pages. `total-recall openwiki ingest <directory> --project` explicitly imports documentation through the existing memory CLI. A successful bootstrap does not claim indexing or runtime readiness.
+
 - **Identifier**: `openwiki`
-- **Version**: 0.1.0
+- **Version**: 0.1.1
 - **SSSS Category**: `openwiki-hubs`
 - **CLI Command**: `npx total-recall openwiki`
 - **UI**: `ui/panel.js` custom element with DESIGN.md tokens

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

@@ -6,11 +6,9 @@
 // Scaffold: report honestly what exists. Add each real subcommand to
 // IMPLEMENTED and to plugin.json "cli.subcommands" as it is built.
 
-import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-
-const TR = process.env.TOTAL_RECALL_BIN || "total-recall";
+import { runBootstrapCommand } from './src/bootstrap.mjs';
 
 async function probeCommand(args) {
   const json = args.includes("--json");
@@ -24,6 +22,7 @@ async function probeCommand(args) {
     const result = { status, ok, latency_ms, endpoint: "/health" };
     if (json) console.log(JSON.stringify(result));
     else console.log(`Health probe: HTTP ${status} (${latency_ms}ms) from ${host}`);
+    if (!ok) process.exitCode = 1;
   } catch (err) {
     const latency_ms = Date.now() - start;
     const result = { status: 503, ok: false, latency_ms, error: err.message };
@@ -84,6 +83,7 @@ const IMPLEMENTED = {};
 IMPLEMENTED.probe = probeCommand;
 IMPLEMENTED.hubs = hubsCommand;
 IMPLEMENTED.ingest = ingestCommand;
+IMPLEMENTED.bootstrap = runBootstrapCommand;
 
 
 export async function run(argv = []) {
@@ -112,12 +112,15 @@ export async function run(argv = []) {
     probe [--json]            Check subsystem health
     hubs [--json]             List indexed documentation hubs
     ingest <path> [options]   Ingest Markdown files into knowledge graph
+    bootstrap --brain <path> [--project-root <path>] [--dry-run] [--json]
+                              Create missing plugin-owned documentation pages
 `);
     return;
   }
 
-  if (IMPLEMENTED[sub]) return IMPLEMENTED[sub](args.slice(1));
+  if (Object.hasOwn(IMPLEMENTED, sub)) return IMPLEMENTED[sub](args.slice(1));
 
+  if (json) console.log(JSON.stringify({ ok: false, error: `OpenWiki operation is not implemented: ${sub}` }));
   console.error(`OpenWiki: "${sub}" is not implemented.`);
   process.exitCode = 2;
 }

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

@@ -1,15 +1,15 @@
 {
   "name": "tr-plugin-openwiki",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-openwiki",
-      "version": "0.1.1",
+      "version": "0.1.2",
       "license": "MIT",
       "devDependencies": {
-        "total-recall-brain": "^3.40.7"
+        "total-recall-brain": "3.41.2"
       }
     },
     "node_modules/@hexagon/base64": {
@@ -2556,9 +2556,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.40.7",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.40.7.tgz",
-      "integrity": "sha512-G+sEWXVucI5Zs8uV1ie8P+mV/6cncWX76ES72T5dnPB3sFAwlcG9ous2SYTUaYUOETGB2vHTSo3cV4XWkHQ0Ww==",
+      "version": "3.41.2",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.2.tgz",
+      "integrity": "sha512-bwJFAFAyvk9ysf+5zhBzMxrKus1Hj1AygUWdBNt+vQbM2sfSEf6701sa30KwfGyU8+cMuN6YNT5Mn63mFZIi/w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

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

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-openwiki",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Multi-repo knowledge graph and documentation wiki engine for Total Recall",
   "scripts": {
@@ -13,6 +13,7 @@
     "README.md",
     "LICENSE",
     "ui/",
-    "src/"
+    "src/",
+    "templates/"
   ]
 }

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.1.1",
+  "version": "0.1.2",
   "description": "Multi-repo knowledge graph and documentation wiki engine for Total Recall.",
   "license": "MIT",
   "branding": {
@@ -83,6 +83,39 @@
         "timeout_ms": 600000,
         "effect": "write"
       },
+      {
+        "name": "bootstrap",
+        "description": "Create missing OpenWiki documentation pages in explicit brain and project directories",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "brain",
+            "flag": "--brain",
+            "label": "Brain directory",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "projectRoot",
+            "flag": "--project-root",
+            "label": "Project root",
+            "type": "string"
+          },
+          {
+            "name": "dryRun",
+            "flag": "--dry-run",
+            "label": "Preview without writing",
+            "type": "boolean"
+          },
+          {
+            "name": "json",
+            "flag": "--json",
+            "label": "JSON output",
+            "type": "boolean"
+          }
+        ]
+      },
       {
         "name": "probe",
         "description": "Run HTTP 200 health verification probe",

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

@@ -0,0 +1,99 @@
+/** Plugin-owned, create-only documentation bootstrap. No host runtime required. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const templatesDir = fileURLToPath(new URL('../templates/openwiki/', import.meta.url));
+
+function requireAbsolute(value, label) {
+  if (typeof value !== 'string' || !value || !path.isAbsolute(value)) throw new Error(`${label} must be an absolute directory path`);
+  return path.resolve(value);
+}
+
+function inspectDirectory(directory) {
+  const stat = fs.lstatSync(directory, { throwIfNoEntry: false });
+  if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) throw new Error(`Unsafe documentation directory: ${directory}`);
+}
+
+function inspectTarget(root) {
+  inspectDirectory(root);
+  const directory = path.join(root, 'openwiki');
+  inspectDirectory(directory);
+  return directory;
+}
+
+/** Preserve every existing page; filesystem projections are not canonical memory. */
+export function bootstrapOpenWiki({ brain, projectRoot = null, dryRun = false } = {}) {
+  const brainRoot = requireAbsolute(brain, '--brain');
+  const project = projectRoot === null ? null : requireAbsolute(projectRoot, '--project-root');
+  const roots = [...new Set([brainRoot, ...(project ? [project] : [])])];
+  const directories = roots.map(inspectTarget);
+  const templates = fs.readdirSync(templatesDir, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name));
+  if (!templates.length || templates.some(entry => !entry.isFile() || !entry.name.endsWith('.md'))) {
+    throw new Error('OpenWiki documentation templates are missing or invalid');
+  }
+
+  // Validate every destination before creating any directory or page.
+  for (const directory of directories) for (const entry of templates) {
+    const destination = path.join(directory, entry.name);
+    const stat = fs.lstatSync(destination, { throwIfNoEntry: false });
+    if (stat && !stat.isFile() && !stat.isSymbolicLink()) throw new Error(`Documentation page is not a file: ${destination}`);
+  }
+
+  const targets = directories.map(directory => {
+    const created = [], preserved = [], planned = [];
+    if (!dryRun) fs.mkdirSync(directory, { recursive: true });
+    for (const entry of templates) {
+      const destination = path.join(directory, entry.name);
+      if (fs.lstatSync(destination, { throwIfNoEntry: false })) {
+        preserved.push(entry.name);
+        continue;
+      }
+      if (dryRun) { planned.push(entry.name); continue; }
+      try {
+        fs.copyFileSync(path.join(templatesDir, entry.name), destination, fs.constants.COPYFILE_EXCL);
+        created.push(entry.name);
+      } catch (err) {
+        // A concurrently authored page belongs to its author, never the template.
+        if (err.code !== 'EEXIST') throw err;
+        preserved.push(entry.name);
+      }
+    }
+    return { directory, created, preserved, planned };
+  });
+  return { ok: true, dry_run: dryRun, targets,
+    files_created: targets.reduce((sum, target) => sum + target.created.length, 0),
+    files_preserved: targets.reduce((sum, target) => sum + target.preserved.length, 0),
+    files_planned: targets.reduce((sum, target) => sum + target.planned.length, 0) };
+}
+
+export async function runBootstrapCommand(args = []) {
+  const json = args.includes('--json');
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: total-recall openwiki bootstrap --brain <absolute-directory> [--project-root <absolute-directory>] [--dry-run] [--json]');
+    return { ok: true, help: true };
+  }
+  try {
+    const options = {};
+    for (let index = 0; index < args.length; index++) {
+      const arg = args[index];
+      if (arg === '--brain' || arg === '--project-root') {
+        const value = args[++index];
+        if (!value || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+        options[arg === '--brain' ? 'brain' : 'projectRoot'] = value;
+      } else if (arg === '--dry-run') options.dryRun = true;
+      else if (arg !== '--json') throw new Error(`Unknown bootstrap option: ${arg}`);
+    }
+    const result = bootstrapOpenWiki(options);
+    if (json) console.log(JSON.stringify(result));
+    else console.log(`OpenWiki: ${result.files_created} pages created, ${result.files_preserved} preserved${result.dry_run ? `, ${result.files_planned} planned (dry run)` : ''}.`);
+    return result;
+  } catch (err) {
+    const result = { ok: false, error: err.message };
+    if (json) console.log(JSON.stringify(result));
+    console.error(`OpenWiki bootstrap failed: ${err.message}`);
+    process.exitCode = 1;
+    return result;
+  }
+}

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

@@ -0,0 +1,10 @@
+# OpenWiki
+
+Portable knowledge documentation for this Total Recall brain.
+
+| Layer | Purpose |
+|-------|---------|
+| **Memory vault** | SSSS nodes (rules, prefs, facts) — machine-enforceable |
+| **OpenWiki** | Human/agent docs (architecture, how-tos, stack notes) |
+
+OpenWiki documentation is provided by the OpenWiki plugin. Edit freely; do not put secrets here.

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

@@ -0,0 +1,5 @@
+# Architecture (this brain)
+
+Describe the systems this brain cares about: repos, stacks, deploy targets.
+
+Project brains should document the local codebase; the global brain documents cross-repo identity and preferences.

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

@@ -0,0 +1,10 @@
+# IDE personalization
+
+```bash
+npx total-recall connect claude-code   # CLAUDE.md
+npx total-recall connect codex         # AGENTS.md
+npx total-recall connect cursor        # .cursor/rules/
+npx total-recall connect gemini        # GEMINI.md
+```
+
+Total Recall only writes inside managed inject markers. Your local rules stay intact.

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

@@ -0,0 +1,11 @@
+# Memory
+
+Use the Total Recall CLI for durable memory:
+
+```bash
+npx total-recall remember invariant "Never commit secrets." --importance 5
+npx total-recall recall "secrets"
+npx total-recall compile
+```
+
+Categories: invariants, preferences, facts, decisions, patterns, anti-patterns, concepts, lore.

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

@@ -0,0 +1,7 @@
+# Secrets & API keys
+
+Manage credentials through the auth plugin: `total-recall auth secret list|set|rotate|audit`.
+
+**Never** put API keys in openwiki pages or compiled IDE instruction files.
+
+Credential values belong in the encrypted auth store, never in documentation.

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

@@ -0,0 +1,7 @@
+# Skills
+
+- **Total Recall skill** (only nested agent skill): `.agent/skills/total-recall/SKILL.md`
+- **User skills**: `.agent/skills/<name>/SKILL.md` — project or global
+- **TR modules** (not skills): `.agent/skills/total-recall/modules/` — internal docs/scripts
+
+TR will track skill installs across repos and support adaptive deploy (see TR_CORE_FOCUS).

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

@@ -6,7 +6,14 @@ tokens:
   wordmark: "[BRAIN//DUMP]"
   color-primary: "#3b82f6"
   color-background: "#0f172a"
+  color-surface: "#1e293b"
   color-accent: "#facc15"
+  color-ok: "#10b981"
+  color-warn: "#f59e0b"
+  color-danger: "#ef4444"
+  color-text: "#f8fafc"
+  color-muted: "#94a3b8"
+  color-line: "#334155"
   badge: "Knowledge Graph"
   font-mono: "'JetBrains Mono', 'Fira Code', monospace"
   border-radius: "8px"
@@ -14,5 +21,12 @@ tokens:
 
 ## Brand & Typographic Wordmark
 - **Name**: Brain Dump
-- **Wordmark Logo**: `[BRAIN//DUMP]` (custom typographic badge, no generic icons)
-- **Palette**: Primary `#3b82f6`, Surface `#0f172a`, Accent `#facc15`.
+- **Wordmark Logo**: `[BRAIN//DUMP]` (custom vector typographic badge, no generic emojis)
+- **Palette**: Primary `#3b82f6`, Surface `#0f172a`, Secondary Surface `#1e293b`, Accent `#facc15`, Line `#334155`, Text `#f8fafc`.
+- **States**: Verified Knowledge `#10b981`, Warning `#f59e0b`, Danger `#ef4444`.
+
+## Interface Architecture
+1. **Header**: Custom vector wordmark, knowledge graph badge, active hub count.
+2. **Hub Tree Matrix**: Grid of verified documentation files (`openwiki/*.md`), rendering title, path, file size in bytes, and line count.
+3. **Structured Ingestion Deck**: Interactive controls for cross-repo documentation ingest with target path input, dry-run toggle, and run button.
+4. **Bootstrap & Inspection Deck**: One-click bootstrap trigger and execution receipts without terminal stdout dumps.