total-recall-brain 3.6.13 → 3.8.0

package/bin/total-recall.mjs

@@ -80,6 +80,7 @@ const COMMANDS = {
   help:     'help.mjs',
   collab:   'collab.mjs',
   command:  'command.mjs',
+  export:   'export.mjs',
 };
 function printHelp() {
   console.log(`
@@ -122,6 +123,7 @@ function printHelp() {
                                      into the vault (run before compile on first install)
     ingest [--watch]    Ingest IDE conversation logs (Claude Code, Codex, Gemini, etc.)
     ingest google-takeout <path>  Ingest Google Takeout export data
+    export <path> --okf Export memory vault as an OKF-compliant bundle
     connect <client>    Configure Cursor, Claude Code, Codex, UltraChat, Gemini, etc.
     sync [--watch]      Pull remote brain instructions into the current workspace
     relay <cmd>         Local background relay: ship IDE sessions to remote brain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.6.13",
+  "version": "3.8.0",
   "description": "Sovereign AI system — database-free, SSSS-powered personal intelligence engine deployable to any POSIX host.",
   "type": "module",
   "bin": {

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

@@ -1,5 +1,4 @@
 ---
-type: skill
 name: total-recall
 description: "Use this skill as the master guide to understand the entire Total Recall Sovereign AI OS setup, VFS topologies, SSSS protocol, CLI parameter reference, troubleshooting, and automated upstream repository sync. MANDATORY: Read this file before attempting major setup modifications or diagnoses."
 ---
@@ -145,6 +144,38 @@ npx total-recall compile
 ```
 Synchronously rebuild the entire memory index (derived embeddings) and regenerate prompt instruction shims (such as `INSTRUCTIONS.md`, `GEMINI.md`, `AGENTS.md`, etc.).
 
+### 5. Ingest OKF Bundle
+```bash
+npx total-recall ingest okf <path> [options]
+```
+Recursively parse and ingest an Open Knowledge Format (OKF v0.1 Draft) bundle directory.
+*   **Options**:
+    *   `--dry-run`: Parse and validate nodes without writing files.
+    *   `--category <name>`: Override and force all imported nodes to a specific category.
+    *   `--importance <1-5>`: Override importance for imported nodes.
+    *   `--on-conflict <strategy>`: Slug conflict behavior (`overwrite`, `skip`, `warn` - default is `warn`).
+    *   `--type-map <json>`: Custom type-to-category mapping JSON.
+*   *Note*: Spawns an asynchronous background surface compile process immediately on successful ingest.
+
+### 6. Export OKF Bundle
+```bash
+npx total-recall export <path> [options]
+```
+Export the memory vault into an OKF-compliant directory structure.
+*   **Options**:
+    *   `--okf`: Run in OKF export mode.
+    *   `--strip-ssss`: Strip all SSSS-specific metadata parameters from output frontmatter.
+    *   `--format <type>`: Package output as archive (`tar.gz`).
+    *   `--global` / `--project`: Target scope layer.
+
+### 7. Lint OKF Compliance
+```bash
+npx total-recall lint --okf [options]
+```
+Scan vault memory nodes and check for OKF metadata compliance (presence of title, description, tags, and updated timestamp).
+*   **Options**:
+    *   `--strict`: Promote compliance warnings to errors and exit with code 1.
+
 ---
 
 ## 🌐 DIRECT REST API REFERENCE

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

@@ -1,8 +1,6 @@
 ---
-type: skill
 name: cli-agents
 description: "Orchestrate headlessly spawned CLI agents from the central registry."
-schema_version: 2
 ---
 
 # CLI Agents — Headless Multi-Agent Orchestration & Dispatch Engine

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

@@ -1,8 +1,6 @@
 ---
-type: skill
 name: ssss
 description: "Use this skill to inspect, validate, write, and manage SSSS primitives, memory nodes, operation envelopes, scope overlays, projections, and VFS specifications in the Total Recall reference kernel. MANDATORY: Read this file before editing SSSS files or code."
-schema_version: 2
 ---
 
 # SSSS — Structured Semantic Syntax System Manager
@@ -127,6 +125,9 @@ SSSS schema v2. Required schema v2 knowledge-graph fields are:
 
 Invariants additionally use `priority: absolute` and `immutable: true`.
 
+### OKF Compatibility Note
+SSSS v0.2 is a strict superset of the Open Knowledge Format (OKF v0.1 Draft). SSSS memory nodes are fully OKF-compatible, as they are Markdown files containing a YAML frontmatter block with a `type` field (which maps to SSSS `category` via the OKF adapter). To bridge the format seamlessly, SSSS v0.2 extends `MemoryNodeSchema` with two optional OKF-standard fields: `description` and `resource` (supporting non-HTTP URIs such as `gs://` or `s3://`).
+
 Memory validation is owned by `TotalRecallMemoryValidator`, not by generic loose
 frontmatter checks. No memory path may be committed with zero validation.
 

package/src/cli/export.mjs

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseLayerFlag, resolveBrainDir } from './agent-dir.mjs';
+import { exportBundle } from '../core/okf-adapter.mjs';
+
+export default async function exportCommand(args) {
+  const { layer, remainingArgs } = parseLayerFlag(args);
+
+  const opts = {
+    outputPath: null,
+    okf: false,
+    format: 'dir',
+    stripSsss: false,
+    help: false
+  };
+
+  for (let i = 0; i < remainingArgs.length; i++) {
+    const arg = remainingArgs[i];
+    const val = remainingArgs[i + 1];
+
+    switch (arg) {
+      case '--okf':
+        opts.okf = true;
+        break;
+      case '--format':
+        if (val) { opts.format = val; i++; }
+        break;
+      case '--strip-ssss':
+        opts.stripSsss = true;
+        break;
+      case '--help': case '-h':
+        opts.help = true;
+        break;
+      default:
+        if (!arg.startsWith('-') && !opts.outputPath) {
+          opts.outputPath = arg;
+        }
+    }
+  }
+
+  if (opts.help || !opts.outputPath || !opts.okf) {
+    printExportHelp();
+    return;
+  }
+
+  const brainDir = resolveBrainDir(layer);
+  const vaultDir = path.join(brainDir, 'memory-vault');
+
+  console.log(`\n  📤 Exporting Memory Vault to OKF Bundle...`);
+  console.log(`  🧠 Source Brain: ${layer} (${vaultDir})`);
+  console.log(`  📂 Destination:  ${opts.outputPath} (Format: ${opts.format})`);
+
+  try {
+    const report = await exportBundle(vaultDir, opts.outputPath, {
+      format: opts.format,
+      stripSsss: opts.stripSsss
+    });
+
+    console.log(`\n  Export Summary:`);
+    console.log(`  🟢 Exported: ${report.exported.length} concepts`);
+    console.log(`  📄 generated index.md`);
+    console.log(`  📄 generated log.md`);
+    console.log(`  ✅ Export completed successfully.\n`);
+  } catch (err) {
+    console.error(`\n  ❌ Export failed: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+function printExportHelp() {
+  console.log(`
+  total-recall export — Export Total Recall knowledge bases
+
+  Usage:
+    total-recall export <output-path> --okf [options]
+
+  Options:
+    --okf                     Export as an Open Knowledge Format (OKF) bundle (required)
+    --format <dir|tar.gz>     Output format: directory or compressed tarball (default: dir)
+    --strip-ssss              Remove all SSSS-specific metadata fields, leaving only pure OKF
+    --global                  Source from the global brain
+    --project                 Source from the project brain (default)
+    --help, -h                Show this help
+  `);
+}

package/src/cli/ingest-okf.mjs

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseLayerFlag, resolveBrainDir } from './agent-dir.mjs';
+import { importBundle } from '../core/okf-adapter.mjs';
+
+export async function runOkfIngest(args) {
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  
+  const opts = {
+    bundlePath: null,
+    dryRun: false,
+    category: null,
+    importance: null,
+    onConflict: 'warn',
+    typeMap: null,
+    help: false
+  };
+
+  for (let i = 0; i < remainingArgs.length; i++) {
+    const arg = remainingArgs[i];
+    const val = remainingArgs[i + 1];
+
+    switch (arg) {
+      case '--dry-run':
+        opts.dryRun = true;
+        break;
+      case '--category':
+        if (val) { opts.category = val; i++; }
+        break;
+      case '--importance':
+        if (val) { opts.importance = parseInt(val, 10); i++; }
+        break;
+      case '--on-conflict':
+        if (val) { opts.onConflict = val; i++; }
+        break;
+      case '--type-map':
+        if (val) {
+          const map = {};
+          const pairs = val.split(',');
+          for (const pair of pairs) {
+            const parts = pair.split('=');
+            if (parts.length === 2) {
+              map[parts[0].trim()] = parts[1].trim();
+            }
+          }
+          opts.typeMap = map;
+          i++;
+        }
+        break;
+      case '--help': case '-h':
+        opts.help = true;
+        break;
+      default:
+        if (!arg.startsWith('-') && !opts.bundlePath) {
+          opts.bundlePath = arg;
+        }
+    }
+  }
+
+  if (opts.help || !opts.bundlePath) {
+    printIngestOkfHelp();
+    return;
+  }
+
+  const brainDir = resolveBrainDir(layer);
+  const vaultDir = path.join(brainDir, 'memory-vault');
+
+  console.log(`\n  📥 Importing OKF Bundle from: ${opts.bundlePath}`);
+  console.log(`  🧠 Target Brain: ${layer} (${vaultDir})`);
+  if (opts.dryRun) console.log('  ⚠️  DRY RUN: No actual writes will be committed.');
+
+  const report = await importBundle(opts.bundlePath, vaultDir, {
+    dryRun: opts.dryRun,
+    category: opts.category,
+    importance: opts.importance,
+    onConflict: opts.onConflict,
+    typeMap: opts.typeMap
+  });
+
+  console.log(`\n  Import Summary:`);
+  console.log(`  🟢 Imported: ${report.imported.length} concepts`);
+  console.log(`  🟡 Skipped:  ${report.skipped.length} concepts`);
+  console.log(`  🔴 Errors:   ${report.errors.length} concepts`);
+
+  if (report.skipped.length > 0) {
+    console.log(`\n  Skipped detail:`);
+    for (const item of report.skipped) {
+      console.log(`    • ${item.file}: ${item.reason}`);
+    }
+  }
+
+  if (report.errors.length > 0) {
+    console.log(`\n  Errors detail:`);
+    for (const item of report.errors) {
+      console.log(`    • ${item.file}: ${item.error}`);
+    }
+    process.exit(1);
+  }
+
+  if (report.imported.length > 0 && !opts.dryRun) {
+    // Recompile active memory surfaces and indexes in the background to avoid blocking the CLI call.
+    console.log('\n  ⏳ Recompiling active memory surfaces and indexes in the background...');
+    try {
+      const { spawn } = await import('node:child_process');
+      const child = spawn(process.argv[0], [process.argv[1], 'compile'], {
+        detached: true,
+        stdio: 'ignore'
+      });
+      child.unref();
+      console.log('  ✅ Background compilation started.');
+    } catch (err) {
+      console.warn(`  ⚠️  Background recompilation spawn failed: ${err.message}`);
+    }
+  }
+}
+
+function printIngestOkfHelp() {
+  console.log(`
+  Usage:
+    total-recall ingest okf <bundle-path> [options]
+
+  Options:
+    --dry-run                 Validate concepts and preview import without writing
+    --category <name>         Override and force category for all imported concepts
+    --importance <1-5>        Override default importance (default: 3)
+    --on-conflict <strategy>  Strategy for duplicate slugs: 'skip' | 'warn' | 'overwrite' (default: warn)
+    --type-map <mapping>      Custom type mappings. Format: "Type A=facts,Type B=concepts"
+    --global                  Target the global brain
+    --project                 Target the project brain (default)
+    --help, -h                Show this help
+  `);
+}

package/src/cli/ingest.mjs

@@ -38,6 +38,8 @@ function printHelp() {
   Subcommands:
     google-takeout <path>  Ingest Google Takeout export data
                            Use 'total-recall ingest google-takeout --help' for details
+    okf <path>             Ingest an Open Knowledge Format (OKF) bundle directory
+                           Use 'total-recall ingest okf --help' for details
 
   IDE Session Ingest:
     Scans known local directories for conversation history from:
@@ -52,6 +54,7 @@ function printHelp() {
   Usage:
     total-recall ingest [options]
     total-recall ingest google-takeout <path> [options]
+    total-recall ingest okf <path> [options]
 
   Options:
     --sources <list>   Comma-separated source filter (e.g. claude-code,codex)
@@ -68,6 +71,12 @@ export default async function ingest(args) {
     return;
   }
 
+  if (args[0] === 'okf') {
+    const { runOkfIngest } = await import('./ingest-okf.mjs');
+    await runOkfIngest(args.slice(1));
+    return;
+  }
+
   const opts = parseArgs(args);
   if (opts.help) { printHelp(); return; }
 

package/src/cli/lint.mjs

@@ -24,12 +24,13 @@ const AGENT_DIR = resolveAgentDir();
 const BRAIN_DIR = resolveBrainDir();
 
 function parseArgs(args) {
-  const opts = { vault: null, strict: false, json: false, help: false };
+  const opts = { vault: null, strict: false, json: false, help: false, okf: false };
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
       case '--vault': opts.vault = args[++i]; break;
       case '--strict': opts.strict = true; break;
       case '--json': opts.json = true; break;
+      case '--okf': opts.okf = true; break;
       case '--help': case '-h': opts.help = true; break;
     }
   }
@@ -38,16 +39,17 @@ function parseArgs(args) {
 
 function printHelp() {
   console.log(`
-  total-recall lint — Validate vault nodes against SSSS schema v2
+  total-recall lint — Validate vault nodes against SSSS schema v2 or OKF spec
 
   Scans all .md files in the memory vault and validates their YAML
-  frontmatter against the Zod schemas defined in src/core/schema.mjs.
+  frontmatter against the Zod schemas or checks for OKF compliance.
 
   Usage: total-recall lint [options]
 
   Options:
     --vault <path>     Override vault directory (default: ~/.agent/memory-vault)
     --strict           Treat warnings as errors (exit 1 on any issue)
+    --okf              Verify OKF v0.1 draft metadata compliance
     --json             Output results as JSONL
     --help, -h         Show this help
 
@@ -63,6 +65,40 @@ export default async function lint(args) {
 
   const vaultDir = opts.vault || path.join(BRAIN_DIR, 'memory-vault');
 
+  if (opts.okf) {
+    const { lintOkfCompliance } = await import('../core/okf-adapter.mjs');
+    const report = lintOkfCompliance(vaultDir, { strict: opts.strict });
+
+    if (opts.json) {
+      console.log(JSON.stringify(report));
+    } else {
+      console.error(`\n  🔍 OKF Compliance Report for: ${vaultDir}\n`);
+      for (const warn of report.warnings) {
+        console.error(`  ⚠️  ${warn.file}: ${warn.message}`);
+      }
+      for (const err of report.errors) {
+        console.error(`  ❌ ${err.file}: ${err.message}`);
+      }
+
+      console.error(`\n  ── Results ──`);
+      console.error(`     Total scanned:  ${report.total}`);
+      console.error(`     Pass:           ${report.pass ? 'Yes' : 'No'}`);
+      console.error(`     Warnings:       ${report.warnings.length}`);
+      console.error(`     Errors:         ${report.errors.length}`);
+
+      if (report.pass) {
+        console.error(`\n  ✅ OKF Compliance passed\n`);
+      } else {
+        console.error(`\n  ❌ OKF Compliance failed\n`);
+      }
+    }
+
+    if (!report.pass) {
+      process.exit(1);
+    }
+    return;
+  }
+
   if (!opts.json) {
     console.error(`\n  🔍 Linting vault: ${vaultDir}\n`);
   }

package/src/core/okf-adapter.mjs

@@ -0,0 +1,543 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import matter from 'gray-matter';
+import { safeStringify } from './vault.mjs';
+import { writeNodeValidated } from './validated-write.mjs';
+import { getNodes } from './vault-cache.mjs';
+import { validateMemoryNode } from './total-recall-memory-validator.mjs';
+
+// ─── DEFAULT OKF TYPE MAP ──────────────────────────────────────────────────
+export const DEFAULT_OKF_TYPE_MAP = {
+  'BigQuery Table':    'facts',
+  'BigQuery Dataset':  'facts',
+  'API Endpoint':      'facts',
+  'Metric':            'concepts',
+  'Playbook':          'patterns',
+  'Runbook':           'patterns',
+  'Reference':         'facts',
+  'Architecture':      'concepts',
+  'Decision':          'decisions',
+  'Policy':            'invariants',
+  'Best Practice':     'patterns',
+  'Anti-Pattern':      'anti-patterns',
+  '*':                 'facts',
+};
+
+// ─── Pure Mapping Functions ────────────────────────────────────────────────
+
+/**
+ * Derives a valid SSSS subject from a title.
+ */
+function deriveSubject(title) {
+  let subject = 'okf.concept';
+  if (title) {
+    const cleaned = title.replace(/[^a-zA-Z0-9_\s.-]/g, '').trim();
+    if (cleaned) {
+      const words = cleaned.split(/\s+/);
+      if (words.length > 0 && words[0]) {
+        subject = words[0].toLowerCase();
+      }
+    }
+  }
+  return /^[a-zA-Z0-9_\s.-]+$/.test(subject) ? subject : 'okf.concept';
+}
+
+/**
+ * Derives a description from a Markdown body if absent.
+ */
+function deriveDescription(body) {
+  if (!body) return undefined;
+  const match = body.trim().match(/^[^.!?\n]+[.!?]/);
+  return match ? match[0].trim() : body.trim().split('\n')[0].trim();
+}
+
+/**
+ * Capitalizes SSSS category to OKF type.
+ */
+function categoryToOkfType(category) {
+  const reverseMap = {
+    'facts': 'Fact',
+    'concepts': 'Concept',
+    'patterns': 'Pattern',
+    'invariants': 'Invariant',
+    'decisions': 'Decision',
+    'anti-patterns': 'Anti-Pattern',
+    'preferences': 'Preference',
+    'corrections': 'Correction',
+    'lore': 'Lore'
+  };
+  return reverseMap[category] || (category.charAt(0).toUpperCase() + category.slice(1));
+}
+
+/**
+ * Convert an OKF concept (frontmatter + body) into an SSSS memory node.
+ */
+export function okfConceptToSsssNode(okfFrontmatter, okfBody, conceptId, options = {}) {
+  if (!okfFrontmatter || typeof okfFrontmatter !== 'object') {
+    return null;
+  }
+
+  const actualTypeMap = { ...DEFAULT_OKF_TYPE_MAP, ...options.typeMap };
+  const okfType = okfFrontmatter.type;
+
+  let category = options.category;
+  if (!category) {
+    category = actualTypeMap[okfType] || actualTypeMap['*'] || 'facts';
+  }
+
+  // Derive slug
+  let slug = conceptId || 'unnamed-concept';
+  if (slug.endsWith('.md')) {
+    slug = slug.slice(0, -3);
+  }
+  slug = slug.replace(/^(\.\.?[\/\\])+/, '').replace(/^[\/\\]+/, '');
+  slug = slug.replace(/[\/\\]/g, '-').toLowerCase();
+
+  const title = okfFrontmatter.title || conceptId || 'Untitled Concept';
+  const subject = okfFrontmatter.title ? deriveSubject(okfFrontmatter.title) : 'okf.concept';
+  const object = okfFrontmatter.type || 'concept';
+
+  // Parse ISO 8601 timestamp
+  let timestamp = new Date().toISOString();
+  if (okfFrontmatter.timestamp) {
+    if (okfFrontmatter.timestamp instanceof Date) {
+      timestamp = okfFrontmatter.timestamp.toISOString();
+    } else if (typeof okfFrontmatter.timestamp === 'string') {
+      timestamp = okfFrontmatter.timestamp;
+    }
+  }
+
+  const importance = (options.importance !== undefined && options.importance !== null)
+    ? options.importance
+    : ((options.defaultImportance !== undefined && options.defaultImportance !== null)
+        ? options.defaultImportance
+        : 3);
+
+  const node = {
+    type: 'memory',
+    slug,
+    category,
+    title,
+    description: okfFrontmatter.description || undefined,
+    resource: okfFrontmatter.resource || undefined,
+    status: 'active',
+    confidence: 0.8,
+    importance,
+    created: timestamp,
+    updated: timestamp,
+    last_accessed: new Date().toISOString(),
+    source: {
+      type: 'okf-import',
+      session_id: crypto.randomUUID(),
+      agent: 'total-recall-cli',
+      evidence_count: 1,
+    },
+    supersedes: [],
+    superseded_by: null,
+    contradicts: [],
+    tags: Array.isArray(okfFrontmatter.tags) ? okfFrontmatter.tags : (okfFrontmatter.tags ? [okfFrontmatter.tags] : []),
+    related: [],
+    routes_to_skills: [],
+    sentiment_polarity: 'descriptive',
+    sentiment_target: subject,
+    modality: 'descriptive',
+    subject,
+    predicate: 'describes',
+    object,
+    decay: {
+      half_life_days: 30,
+      access_count: 0,
+    },
+    schema_version: 2,
+    body: okfBody || '',
+  };
+
+  return node;
+}
+
+/**
+ * Convert an SSSS memory node into an OKF-compliant concept.
+ */
+export function ssssNodeToOkfConcept(ssssNode) {
+  if (!ssssNode || typeof ssssNode !== 'object') {
+    return null;
+  }
+
+  const desc = ssssNode.description || deriveDescription(ssssNode.body);
+
+  const frontmatter = {
+    ...ssssNode,
+    type: categoryToOkfType(ssssNode.category),
+    title: ssssNode.title,
+    description: desc || undefined,
+    resource: ssssNode.resource || undefined,
+    tags: ssssNode.tags || [],
+    timestamp: ssssNode.updated || ssssNode.created || new Date().toISOString(),
+  };
+
+  // Clean up SSSS node-specific keys we don't want as top-level frontmatter if they match the body/filepath fields
+  delete frontmatter.body;
+  delete frontmatter._filePath;
+  delete frontmatter._filepath;
+  delete frontmatter._file_path;
+
+  return {
+    frontmatter,
+    body: ssssNode.body || '',
+  };
+}
+
+// ─── Bundle Operations (Placeholders to be fully implemented) ────────────────
+
+export async function importBundle(bundlePath, vaultDir, options = {}) {
+  const imported = [];
+  const skipped = [];
+  const errors = [];
+
+  if (!fs.existsSync(bundlePath)) {
+    errors.push({ file: bundlePath, error: 'Bundle directory does not exist' });
+    return { imported, skipped, errors };
+  }
+
+  // Helper to walk directory recursively, skipping index.md and log.md
+  function walk(dir) {
+    let files = [];
+    const list = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of list) {
+      const name = entry.name;
+      // Skip reserved filenames at any directory level
+      if (name === 'index.md' || name === 'log.md') {
+        continue;
+      }
+      const fullPath = path.join(dir, name);
+      if (entry.isDirectory()) {
+        files = files.concat(walk(fullPath));
+      } else if (name.endsWith('.md')) {
+        files.push(fullPath);
+      }
+    }
+    return files;
+  }
+
+  let mdFiles = [];
+  try {
+    mdFiles = walk(bundlePath);
+  } catch (err) {
+    errors.push({ file: bundlePath, error: err.message });
+    return { imported, skipped, errors };
+  }
+
+  // Get existing slugs to handle conflicts
+  let existingSlugs = new Set();
+  try {
+    const existing = getNodes(vaultDir);
+    existingSlugs = new Set(existing.map(n => n.slug));
+  } catch (err) {
+    // If vault dir doesn't exist yet, it's fine, we'll create it during writes
+  }
+
+  const onConflict = options.onConflict || 'warn';
+
+  for (const filePath of mdFiles) {
+    const relPath = path.relative(bundlePath, filePath);
+    let raw;
+    try {
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch (err) {
+      errors.push({ file: relPath, error: `Failed to read file: ${err.message}` });
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = matter(raw);
+    } catch (err) {
+      errors.push({ file: relPath, error: `Failed to parse YAML frontmatter: ${err.message}` });
+      continue;
+    }
+
+    // Skip if there's no frontmatter data or if the required OKF 'type' field is missing
+    if (!parsed || !parsed.data || Object.keys(parsed.data).length === 0 || !parsed.data.type) {
+      skipped.push({ file: relPath, reason: 'missing frontmatter or type field' });
+      continue;
+    }
+
+    const node = okfConceptToSsssNode(parsed.data, parsed.content, relPath, options);
+    if (!node) {
+      skipped.push({ file: relPath, reason: 'failed to map to SSSS node' });
+      continue;
+    }
+
+    // Handle slug conflict
+    if (existingSlugs.has(node.slug)) {
+      if (onConflict === 'skip') {
+        skipped.push({ file: relPath, reason: `conflict (slug ${node.slug} exists)` });
+        continue;
+      } else if (onConflict === 'warn') {
+        console.warn(`[OKF Import Warning] Slug collision: '${node.slug}' already exists. Overwriting.`);
+      }
+    }
+
+    try {
+      const writeResult = writeNodeValidated(node, vaultDir, {
+        dryRun: options.dryRun || false,
+        agentRole: options.agentRole || 'admin'
+      });
+
+      if (!writeResult.success) {
+        let errMsg = writeResult.error || 'Validation failed';
+        if (writeResult.repair?.field_errors) {
+          const details = writeResult.repair.field_errors.map(fe => `${fe.field}: ${fe.issue}`).join(', ');
+          errMsg += ` (${details})`;
+        }
+        errors.push({ file: relPath, error: errMsg });
+      } else {
+        imported.push({ slug: node.slug, file: relPath });
+        if (!options.dryRun) {
+          existingSlugs.add(node.slug);
+        }
+      }
+    } catch (err) {
+      errors.push({ file: relPath, error: `Write error: ${err.message}` });
+    }
+  }
+
+  return { imported, skipped, errors };
+}
+
+export async function exportBundle(vaultDir, outputDir, options = {}) {
+  const { execSync } = await import('node:child_process');
+  const os = await import('node:os');
+
+  const format = options.format || 'dir';
+  const stripSsss = options.stripSsss || false;
+
+  let targetDir = outputDir;
+  let isTar = format === 'tar.gz';
+  let tempDir = null;
+
+  if (isTar) {
+    tempDir = path.join(os.tmpdir(), `okf-export-${crypto.randomUUID()}`);
+    targetDir = tempDir;
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const nodes = getNodes(vaultDir);
+  const exported = [];
+
+  const conceptsByCategory = {};
+
+  for (const node of nodes) {
+    const concept = ssssNodeToOkfConcept(node);
+    if (!concept) continue;
+
+    if (stripSsss) {
+      const allowed = ['type', 'title', 'description', 'resource', 'tags', 'timestamp'];
+      const stripped = {};
+      for (const key of allowed) {
+        if (concept.frontmatter[key] !== undefined) {
+          stripped[key] = concept.frontmatter[key];
+        }
+      }
+      concept.frontmatter = stripped;
+    }
+
+    const category = node.category || 'facts';
+    const catDir = path.join(targetDir, category);
+    fs.mkdirSync(catDir, { recursive: true });
+
+    const filename = `${node.slug}.md`;
+    const destPath = path.join(catDir, filename);
+
+    const fileContent = safeStringify(concept.body, concept.frontmatter);
+    fs.writeFileSync(destPath, fileContent, 'utf8');
+
+    exported.push({ slug: node.slug, file: path.join(category, filename) });
+
+    if (!conceptsByCategory[category]) {
+      conceptsByCategory[category] = [];
+    }
+    conceptsByCategory[category].push({
+      title: node.title,
+      relPath: `./${category}/${filename}`,
+      description: concept.frontmatter.description || ''
+    });
+  }
+
+  // Generate index.md
+  let indexContent = '# Knowledge Bundle Index\n\n';
+  for (const [category, list] of Object.entries(conceptsByCategory)) {
+    const catHeader = category.charAt(0).toUpperCase() + category.slice(1);
+    indexContent += `## ${catHeader}\n`;
+    for (const item of list) {
+      const descSuffix = item.description ? ` - ${item.description}` : '';
+      indexContent += `- [${item.title}](${item.relPath})${descSuffix}\n`;
+    }
+    indexContent += '\n';
+  }
+  fs.writeFileSync(path.join(targetDir, 'index.md'), indexContent, 'utf8');
+
+  // Generate log.md
+  let logContent = '# Bundle Update History\n\n';
+  const auditPath = path.join(vaultDir, '.events', 'audit.jsonl');
+  if (fs.existsSync(auditPath)) {
+    try {
+      const lines = fs.readFileSync(auditPath, 'utf8').trim().split('\n');
+      for (const line of lines) {
+        if (!line) continue;
+        const event = JSON.parse(line);
+        const date = event.ts ? new Date(event.ts).toISOString().replace(/\.\d+Z$/, 'Z') : 'Unknown Date';
+        const operation = event.payload?.resolved_type || 'mutation';
+        logContent += `- **${date}**: Operation '${operation}' committed at \`${event.subject || event.path || ''}\`\n`;
+      }
+    } catch (err) {
+      logContent += `Failed to parse audit history: ${err.message}\n`;
+    }
+  } else {
+    logContent += 'No update history available.\n';
+  }
+  fs.writeFileSync(path.join(targetDir, 'log.md'), logContent, 'utf8');
+
+  if (isTar) {
+    const tarFile = outputDir.endsWith('.tar.gz') ? outputDir : `${outputDir}.tar.gz`;
+    fs.mkdirSync(path.dirname(tarFile), { recursive: true });
+    execSync(`tar -czf "${tarFile}" -C "${targetDir}" .`);
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+
+  return {
+    exported,
+    indexGenerated: true,
+    logGenerated: true
+  };
+}
+
+export function lintOkfCompliance(vaultDir, options = {}) {
+  const strict = options.strict || false;
+  const nodes = getNodes(vaultDir);
+
+  const warnings = [];
+  const errors = [];
+
+  for (const node of nodes) {
+    const relPath = `${node.category}/${node.slug}.md`;
+    
+    // Check title
+    if (!node.title) {
+      const msg = `Missing title in ${relPath}`;
+      if (strict) errors.push({ file: relPath, message: msg });
+      else warnings.push({ file: relPath, message: msg });
+    }
+
+    // Check description
+    if (!node.description) {
+      const msg = `Missing description in ${relPath}`;
+      if (strict) errors.push({ file: relPath, message: msg });
+      else warnings.push({ file: relPath, message: msg });
+    }
+
+    // Check tags
+    if (!node.tags || !Array.isArray(node.tags) || node.tags.length === 0) {
+      const msg = `Missing or empty tags in ${relPath}`;
+      if (strict) errors.push({ file: relPath, message: msg });
+      else warnings.push({ file: relPath, message: msg });
+    }
+
+    // Check updated/created timestamp
+    if (!node.updated && !node.created) {
+      const msg = `Missing updated/created timestamp in ${relPath}`;
+      if (strict) errors.push({ file: relPath, message: msg });
+      else warnings.push({ file: relPath, message: msg });
+    }
+  }
+
+  const pass = errors.length === 0;
+
+  return {
+    total: nodes.length,
+    pass,
+    warnings,
+    errors
+  };
+}
+
+export function generateLiveIndex(vaultDir) {
+  const nodes = getNodes(vaultDir);
+  if (nodes.length === 0) return;
+  
+  const conceptsByType = {};
+
+  for (const node of nodes) {
+    const concept = ssssNodeToOkfConcept(node);
+    if (!concept) continue;
+
+    const type = concept.frontmatter.type || 'Generic Concept';
+    const category = node.category || 'facts';
+    const filename = `${node.slug}.md`;
+
+    if (!conceptsByType[type]) {
+      conceptsByType[type] = [];
+    }
+    conceptsByType[type].push({
+      title: node.title || node.slug,
+      relPath: `./${category}/${filename}`,
+      description: concept.frontmatter.description || ''
+    });
+  }
+
+  let indexContent = '# Knowledge Bundle Index\n\n';
+  const sortedTypes = Object.keys(conceptsByType).sort();
+  for (const type of sortedTypes) {
+    indexContent += `# ${type}\n\n`;
+    const list = conceptsByType[type].sort((a, b) => a.title.localeCompare(b.title));
+    for (const item of list) {
+      const descSuffix = item.description ? ` - ${item.description}` : '';
+      indexContent += `* [${item.title}](${item.relPath})${descSuffix}\n`;
+    }
+    indexContent += '\n';
+  }
+  fs.writeFileSync(path.join(vaultDir, 'index.md'), indexContent, 'utf8');
+}
+
+export function generateLiveLog(vaultDir) {
+  let logContent = '# Bundle Update History\n\n';
+  const auditPath = path.join(vaultDir, '.events', 'audit.jsonl');
+  if (fs.existsSync(auditPath)) {
+    try {
+      const lines = fs.readFileSync(auditPath, 'utf8').trim().split('\n').filter(Boolean);
+      const eventsByDate = {};
+
+      for (const line of lines) {
+        const event = JSON.parse(line);
+        if (!event.ts) continue;
+        const dateStr = new Date(event.ts).toISOString().split('T')[0];
+        const operation = event.payload?.resolved_type || 'mutation';
+        const formattedOp = operation.charAt(0).toUpperCase() + operation.slice(1);
+        const subject = event.subject || event.path || 'unknown';
+        
+        if (!eventsByDate[dateStr]) {
+          eventsByDate[dateStr] = [];
+        }
+        eventsByDate[dateStr].push(`* **${formattedOp}**: Committed at \`${subject}\``);
+      }
+
+      const sortedDates = Object.keys(eventsByDate).sort().reverse();
+      for (const date of sortedDates) {
+        logContent += `## ${date}\n`;
+        const logs = eventsByDate[date].reverse();
+        for (const log of logs) {
+          logContent += `${log}\n`;
+        }
+        logContent += '\n';
+      }
+    } catch (err) {
+      logContent += `Failed to parse audit history: ${err.message}\n`;
+    }
+  } else {
+    logContent += 'No update history available.\n';
+  }
+  fs.writeFileSync(path.join(vaultDir, 'log.md'), logContent, 'utf8');
+}
+

package/src/core/schema.mjs

@@ -23,6 +23,8 @@ export const MemoryNodeSchema = z.object({
   slug: z.string(),
   category: z.string(),
   title: z.string(),
+  description: z.string().optional(),
+  resource: z.string().optional(),
   status: z.enum(['active', 'superseded', 'deprecated', 'draft']),
   confidence: z.number().min(0).max(1).optional(),
   importance: z.number().int().min(1).max(5).optional(),

package/src/core/surface.mjs

@@ -10,13 +10,29 @@ import {
 } from './memory-layers.mjs';
 
 /**
- * Extract [[slug]] wikilink references from body text.
+ * Extract [[slug]] wikilink references and relative Markdown link targets from body text.
  * Native TR link resolution; Obsidian renders them as graph edges.
  */
 export function extractWikilinks(body) {
   if (!body) return [];
   const matches = body.match(/\[\[([^\]]+)\]\]/g) || [];
-  return [...new Set(matches.map(m => m.slice(2, -2).split('|')[0].trim()))];
+  const wikilinks = matches.map(m => m.slice(2, -2).split('|')[0].trim());
+
+  const mdLinkMatches = body.matchAll(/\[([^\]]*)\]\(([^)]+)\)/g);
+  const mdLinks = [];
+  for (const match of mdLinkMatches) {
+    const url = match[2].trim();
+    if (/^https?:\/\//i.test(url)) {
+      continue;
+    }
+    const base = path.basename(url);
+    const targetSlug = base.endsWith('.md') ? base.slice(0, -3) : base;
+    if (targetSlug) {
+      mdLinks.push(targetSlug);
+    }
+  }
+
+  return [...new Set([...wikilinks, ...mdLinks])];
 }
 
 /**
@@ -145,15 +161,56 @@ function saveCompactedRulesCache(derivedDir, cache) {
   }
 }
 
+/**
+ * Map a node's modality field to a compact marker for compiled shims.
+ * Gives agents instant priority signal per OKF §4.1 typed-concept pattern.
+ */
+function modalityMarker(node) {
+  const m = (node.modality || '').toLowerCase();
+  if (m === 'must') return '[MUST]';
+  if (m === 'must_not') return '[MUST NOT]';
+  if (m === 'should') return '[SHOULD]';
+  if (m === 'should_not') return '[SHOULD NOT]';
+  // Fallback: infer from category
+  if (node.category === 'invariants') return '[MUST]';
+  if (node.category === 'anti-patterns') return '[CORRECTION]';
+  if (node.category === 'preferences') return '[PREF]';
+  return '';
+}
+
 /**
  * Heuristically summarize a memory node.
+ * OKF-aligned: modality markers, no title/body duplication, sentence-boundary truncation.
  */
 export function heuristicCompact(node) {
   const title = (node.title || '').trim();
   const text = (node.body || node.content || '').trim();
+  const marker = modalityMarker(node);
+  const prefix = marker ? `${marker} ` : '';
+
+  // Determine the best display text, avoiding title/body duplication.
+  // When title is auto-generated ("Self-captured memory: ...") it echoes the body —
+  // use the body directly to avoid doubling the same content.
+  const titleIsEcho = title.startsWith('Self-captured memory:') ||
+    (text && title.length > 20 && text.toLowerCase().startsWith(title.toLowerCase().slice(0, 20)));
+
+  if (node.category && ['invariants', 'preferences', 'anti-patterns'].includes(node.category)) {
+    if (text) {
+      if (titleIsEcho) {
+        // Use body directly — title would duplicate it
+        return `${prefix}${_truncateAtSentence(text, 180)}`;
+      }
+      const lines = text.split('\n');
+      if (lines.length > 1) {
+        return `${prefix}${title}:\n  ${lines.map(l => l.trim()).join('\n  ')}`;
+      }
+      return `${prefix}${title}: ${text}`;
+    }
+    return `${prefix}${title}`;
+  }
   
-  let summary = title;
-  if (text) {
+  let summary = titleIsEcho && text ? text : title;
+  if (text && !titleIsEcho) {
     const firstLine = text.split('\n').map(l => l.trim()).filter(Boolean)[0] || '';
     if (firstLine && 
         !title.toLowerCase().includes(firstLine.toLowerCase()) && 
@@ -164,24 +221,42 @@ export function heuristicCompact(node) {
   }
   
   summary = summary.replace(/\s+/g, ' ');
-  if (summary.length > 180) {
-    summary = summary.substring(0, 180).trim() + '... (use recall to read more)';
+  return `${prefix}${_truncateAtSentence(summary, 180)}`;
+}
+
+/**
+ * Truncate text at the nearest sentence boundary before maxLen,
+ * or at maxLen if no sentence boundary is found.
+ */
+function _truncateAtSentence(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  // Look for sentence-ending punctuation before maxLen
+  const slice = text.substring(0, maxLen);
+  const lastSentence = Math.max(
+    slice.lastIndexOf('. '),
+    slice.lastIndexOf('! '),
+    slice.lastIndexOf('? ')
+  );
+  if (lastSentence > maxLen * 0.4) {
+    return text.substring(0, lastSentence + 1).trim() + ' (use recall to read more)';
   }
-  return summary;
+  return slice.trim() + '... (use recall to read more)';
 }
 
 /**
  * Compact a single memory node using LLM or heuristic fallback.
+ * When force=true, bypass cache read but still write back (OKF augmentation pattern).
  */
-async function compactNode(node, derivedDir) {
+async function compactNode(node, derivedDir, force = false) {
   const title = (node.title || '').trim();
   const body = (node.body || node.content || '').trim();
   const fullText = `${title}\n\n${body}`;
   const contentHash = crypto.createHash('sha256').update(fullText).digest('hex');
 
-  // Load from cache if possible
+  // Load from cache if possible — skip when force=true to recompute from scratch.
+  // Per OKF augmentation pattern: force bypasses cache *read* but preserves cache *write*.
   let cache = {};
-  if (derivedDir) {
+  if (derivedDir && !force) {
     cache = loadCompactedRulesCache(derivedDir);
     if (cache[node.slug] && cache[node.slug].content_sha256 === contentHash) {
       return cache[node.slug].compacted;
@@ -210,8 +285,13 @@ async function compactNode(node, derivedDir) {
     }
   }
 
-  // Save to cache
+  // Save to cache — always merge into existing cache (OKF non-destructive augmentation).
+  // When force=true we skipped cache loading above, so reload it now before writing
+  // to avoid blowing away other nodes' cached compactions.
   if (derivedDir) {
+    if (force) {
+      cache = loadCompactedRulesCache(derivedDir);
+    }
     cache[node.slug] = {
       compacted,
       content_sha256: contentHash,
@@ -223,87 +303,23 @@ async function compactNode(node, derivedDir) {
   return compacted;
 }
 
-export async function buildRulesBlock(skillsDir, nodes = [], { consumer = 'ide', derivedDir } = {}) {
+export async function buildRulesBlock(skillsDir, nodes = [], { consumer = 'ide', derivedDir, force = false } = {}) {
   let combined;
 
   if (consumer === 'api') {
     // API consumers don't need CLI quickstart docs
     combined = `## Total Recall — Active Memory Context\n\nYour memories and rules are loaded from the active brain vault.\n`;
   } else {
-    // CLI quickstart is always included so agents know TR is installed
+    // Compact CLI reference (OKF §6 progressive disclosure — summary, not full manual)
     combined = `## Total Recall — Sovereign Memory System (Installed)
 
-You have Total Recall installed. Use these CLI commands to remember and recall information.
-
-### npx total-recall remember <category> "<content>" [options]
-Save rules, preferences, corrections, and facts to permanent memory.
-
-**Categories:** invariant, preference, correction, fact, concept, pattern, anti-pattern, decision, lore
-
-**Options:**
-  --tags, -t <list>          Comma-separated tags (e.g. "config,server")
-  --importance, -i <1-5>     Importance level (default: 3)
-  --priority, -p <level>     absolute | high | normal | low (default: normal)
-  --modality, -m <type>      must | must_not | should | should_not | descriptive | preference
-  --confidence, -c <0-1>     Confidence level (default: 1.0)
-  --slug <custom-slug>       Custom kebab-case slug
-  --title <custom-title>     Custom human-readable title
-  --status <state>           active | draft | archived (default: active)
-  --related <list>           Comma-separated related slugs
-  --global                   Save to global brain (identity layer)
-  --project                  Save to project brain (context layer)
-
-**Examples:**
-  npx total-recall remember invariant "Never run tsc directly." --importance 5 --priority absolute
-  npx total-recall remember preference "Always use single quotes." --tags "style,js"
-  npx total-recall remember fact "The server runs on port 3000." --importance 4
-  npx total-recall remember fact "Uses Drizzle ORM" --project
-
-### npx total-recall recall "<query>" [options]
-Semantic search across rules, facts, and session history.
-
-**Options:**
-  --top-k, -k <number>       Results to return (default: 5, max: 20)
-  --no-sessions, -ns         Exclude session chunks, vault only
-  --format, -f <type>        text (default) or json
-  --category, -cat <name>    Filter by SSSS category
-  --tags, -t <list>          Filter by tags
-  --modality, -m <type>      Filter by modality
-  --importance, -i <1-5>     Filter by minimum importance
-  --global                   Search global brain only
-  --project                  Search project brain only
-
-**Examples:**
-  npx total-recall recall "Never run tsc directly"
-  npx total-recall recall "Express server port" --top-k 3
-  npx total-recall recall "tsc" --category invariants --modality must
-
-### npx total-recall forget <slug> [options]
-Delete a memory node by slug. Auto-recompiles surfaces and propagates to project brains.
-
-**Options:**
-  --global                   Delete from global brain
-  --project                  Delete from project brain
-  --no-compile               Skip auto-recompilation after deletion
-
-**Examples:**
-  npx total-recall forget old-invariant-slug
-  npx total-recall forget stale-fact --global
-  npx total-recall forget project-specific-node --project
-
-### npx total-recall help <topic>
-Query interactive local documentation, VFS specifications, and command references.
-
-**Options:**
-  --json, -j               Emit machine-readable JSON (ideal for programmatic retrieval)
-
-**Examples:**
-  npx total-recall help connect
-  npx total-recall help architecture
-  npx total-recall help ssss
-
-### npx total-recall --help
-Show all available commands.
+**Quick Reference:**
+- \`npx total-recall remember <category> "<content>" [options]\` — Save to memory (categories: invariant, preference, correction, fact, concept, pattern, anti-pattern, decision, lore; key flags: --importance, --priority, --modality, --tags, --global, --project)
+- \`npx total-recall recall "<query>" [options]\` — Search memory (--top-k, --category, --tags, --modality)
+- \`npx total-recall forget <slug> [options]\` — Delete a memory node (--global, --project)
+- \`npx total-recall compile\` — Rebuild instruction surfaces
+- \`npx total-recall help <topic>\` — Query local documentation
+- \`npx total-recall --help\` — Full CLI reference
 `;
   }
 
@@ -324,10 +340,35 @@ Show all available commands.
   const preferences = nodes.filter(n => n.category === 'preferences' && n.status === 'active' && !isExpired(n));
   const corrections = nodes.filter(n => n.category === 'anti-patterns' && n.status === 'active' && !isExpired(n));
 
+  // Deduplicate nodes by compacted content hash (OKF non-destructive merge pattern).
+  // When two nodes produce identical compacted text, keep the one with higher importance.
+  const deduplicateNodes = (list) => {
+    const seen = new Map();
+    const deduped = [];
+    for (const n of list) {
+      const key = (n.body || n.content || '').trim().toLowerCase().substring(0, 200);
+      if (seen.has(key)) {
+        const existing = seen.get(key);
+        if ((n.importance || 3) > (existing.importance || 3)) {
+          // Replace with higher-importance node
+          const idx = deduped.indexOf(existing);
+          if (idx !== -1) deduped[idx] = n;
+          seen.set(key, n);
+        }
+        // else skip the lower-importance duplicate
+      } else {
+        seen.set(key, n);
+        deduped.push(n);
+      }
+    }
+    return deduped;
+  };
+
   const formatNodes = async (list) => {
+    const unique = deduplicateNodes(list);
     const formatted = [];
-    for (const n of list) {
-      const snippet = await compactNode(n, derivedDir);
+    for (const n of unique) {
+      const snippet = await compactNode(n, derivedDir, force);
       formatted.push(snippet.startsWith('-') ? snippet : `- ${snippet}`);
     }
     return formatted.join('\n');
@@ -412,9 +453,9 @@ function injectDirectives(fileContent, rulesBlock) {
 /**
  * Write or update a platform instruction shim with the pointer and active rules.
  */
-async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir } = {}) {
+async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir, force = false } = {}) {
   const shimDir = path.dirname(shimPath);
-  const rulesBlock = await buildRulesBlock(skillsDir, nodes, { vaultDir, derivedDir });
+  const rulesBlock = await buildRulesBlock(skillsDir, nodes, { vaultDir, derivedDir, force });
   const baseline = 'Read and follow .agent/skills/total-recall/SKILL.md on every turn.\n';
   const fullContent = `${baseline}\n${DIRECTIVES_BEGIN}\n${rulesBlock}\n${DIRECTIVES_END}\n`;
 
@@ -496,13 +537,13 @@ function readConnectedClients(clientsPath) {
 /**
  * Compile shims asynchronously.
  */
-async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultDir, derivedDir } = {}) {
+async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultDir, derivedDir, force = false } = {}) {
   const agentDir = path.dirname(instructionsFile);
   const baseDir = path.basename(agentDir) === '.agent' ? path.dirname(agentDir) : agentDir;
   let injectedCount = 0;
 
   // Always write the canonical INSTRUCTIONS.md
-  if (await writeShim(path.join(baseDir, 'INSTRUCTIONS.md'), skillsDir, nodes, { vaultDir, derivedDir })) {
+  if (await writeShim(path.join(baseDir, 'INSTRUCTIONS.md'), skillsDir, nodes, { vaultDir, derivedDir, force })) {
     injectedCount++;
   }
 
@@ -516,7 +557,7 @@ async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultD
       const files = CLIENT_SHIMS[client];
       if (!files) continue;
       for (const file of files) {
-        if (await writeShim(path.join(baseDir, file), skillsDir, nodes, { vaultDir, derivedDir })) {
+        if (await writeShim(path.join(baseDir, file), skillsDir, nodes, { vaultDir, derivedDir, force })) {
           injectedCount++;
         }
       }
@@ -551,7 +592,7 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
   }
 
   // 1. Write pointer and active rules to all instruction shims
-  const skillsInjected = await compilePointers(instructionsFile, skillsDir, nodes, { vaultDir, derivedDir });
+  const skillsInjected = await compilePointers(instructionsFile, skillsDir, nodes, { vaultDir, derivedDir, force });
 
   // 2. Build derived indexes (powers semantic search API)
   if (!fs.existsSync(derivedDir)) {
@@ -564,7 +605,8 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
     category: n.category,
     status: n.status,
     confidence: n.confidence,
-    memory_layer: inferMemoryLayer(n)
+    memory_layer: inferMemoryLayer(n),
+    links: extractWikilinks(n.body || '')
   }));
   atomicWrite(path.join(derivedDir, 'graph-index.jsonl'), graphIndex.map(n => JSON.stringify(n)).join('\n'));
   atomicWrite(
@@ -589,6 +631,15 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
   atomicWrite(hashFile, currentHash);
   writeProjectionManifest(derivedDir, currentHash);
 
+  // 6. Generate live OKF Index and Log
+  try {
+    const { generateLiveIndex, generateLiveLog } = await import('./okf-adapter.mjs');
+    generateLiveIndex(vaultDir);
+    generateLiveLog(vaultDir);
+  } catch (err) {
+    logger.warn('surface', `Failed to generate live OKF index/log: ${err.message}`);
+  }
+
   return {
     nodesProcessed: nodes.length,
     skillsInjected,