llm-wikis 0.1.0

package/.gitattributes

@@ -0,0 +1,3 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.psd filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "llm-wikis",
+  "version": "0.1.0",
+  "description": "Multi-wiki sync observability for the Karpathy LLM Wiki pattern",
+  "license": "MIT",
+  "bin": {
+    "wiki-scan": "scripts/wiki-scan.js",
+    "wiki-ingest-record": "scripts/wiki-ingest-record.js",
+    "wiki-status-html": "scripts/wiki-status-html.js"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/postinstall.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const src = path.join(__dirname, 'skill');
+const dest = path.join(os.homedir(), '.claude', 'skills', 'wiki');
+
+try {
+  fs.mkdirSync(dest, { recursive: true });
+  fs.cpSync(src, dest, { recursive: true, force: true });
+  console.log('[llm-wiki-sync] Skill installed to ~/.claude/skills/wiki/');
+} catch (err) {
+  console.warn('[llm-wiki-sync] Could not install skill:', err.message);
+  console.warn('[llm-wiki-sync] Manually copy the skill/ directory to ~/.claude/skills/wiki/');
+}

package/scripts/wiki-ingest-record.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+function usage() {
+  console.error('Usage:');
+  console.error('  wiki-ingest-record <wiki-path> <raw-file-relpath> <wiki-page-relpath>');
+  console.error('  wiki-ingest-record <wiki-path> <raw-file-relpath> --update-hash-only');
+  console.error('  wiki-ingest-record <wiki-path> --defer <raw-file-relpath>');
+  process.exit(1);
+}
+
+function sha256(filePath) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
+function loadManifest(wikiPath) {
+  const manifestPath = path.join(wikiPath, '.wiki-manifest.json');
+  return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+
+function saveManifest(wikiPath, manifest) {
+  const manifestPath = path.join(wikiPath, '.wiki-manifest.json');
+  const backupPath = path.join(wikiPath, '.wiki-manifest.backup.json');
+  const tmpPath = manifestPath + '.tmp';
+
+  if (fs.existsSync(manifestPath)) {
+    fs.copyFileSync(manifestPath, backupPath);
+  }
+
+  fs.writeFileSync(tmpPath, JSON.stringify(manifest, null, 2));
+  fs.renameSync(tmpPath, manifestPath);
+}
+
+const [,, wikiPath, arg2, arg3] = process.argv;
+
+if (!wikiPath || !arg2) usage();
+
+const absWikiPath = path.resolve(wikiPath);
+
+// Mode: --defer <raw-file>
+if (arg2 === '--defer') {
+  const rawRel = arg3;
+  if (!rawRel) usage();
+
+  const rawAbs = path.join(absWikiPath, rawRel);
+  if (!fs.existsSync(rawAbs)) {
+    console.error(`File not found: ${rawAbs}`);
+    process.exit(1);
+  }
+
+  const manifest = loadManifest(absWikiPath);
+  const hash = sha256(rawAbs);
+  const mtimeMs = fs.statSync(rawAbs).mtimeMs;
+
+  manifest.raw_to_wiki[rawRel] = {
+    hash,
+    modified: mtimeMs,
+    ingested: null,
+    deferred: true,
+    wiki_pages: manifest.raw_to_wiki[rawRel]?.wiki_pages ?? [],
+  };
+
+  saveManifest(absWikiPath, manifest);
+  console.log(`[wiki-ingest-record] Deferred: ${rawRel}`);
+  process.exit(0);
+}
+
+const rawRel = arg2;
+const wikiPageArg = arg3;
+
+if (!wikiPageArg) usage();
+
+// Mode: --update-hash-only
+if (wikiPageArg === '--update-hash-only') {
+  const manifest = loadManifest(absWikiPath);
+  const entry = manifest.raw_to_wiki[rawRel];
+
+  if (!entry || !entry.wiki_pages || entry.wiki_pages.length === 0) {
+    console.error(`No wiki pages found for ${rawRel} in manifest`);
+    process.exit(1);
+  }
+
+  for (const wikiPage of entry.wiki_pages) {
+    const wikiAbs = path.join(absWikiPath, wikiPage);
+    if (!fs.existsSync(wikiAbs)) continue;
+    const hash = sha256(wikiAbs);
+    const mtimeMs = fs.statSync(wikiAbs).mtimeMs;
+    if (manifest.wiki_to_raw[wikiPage]) {
+      manifest.wiki_to_raw[wikiPage].hash = hash;
+      manifest.wiki_to_raw[wikiPage].last_compiled = mtimeMs;
+    }
+  }
+
+  saveManifest(absWikiPath, manifest);
+  console.log(`[wiki-ingest-record] Updated hash only for: ${rawRel}`);
+  process.exit(0);
+}
+
+// Mode: record raw → wiki page
+const wikiPageRel = wikiPageArg;
+const rawAbs = path.join(absWikiPath, rawRel);
+const wikiAbs = path.join(absWikiPath, wikiPageRel);
+
+if (!fs.existsSync(rawAbs)) {
+  console.error(`Raw file not found: ${rawAbs}`);
+  process.exit(1);
+}
+if (!fs.existsSync(wikiAbs)) {
+  console.error(`Wiki page not found: ${wikiAbs}`);
+  process.exit(1);
+}
+
+const manifest = loadManifest(absWikiPath);
+
+const rawHash = sha256(rawAbs);
+const rawMtime = fs.statSync(rawAbs).mtimeMs;
+const wikiHash = sha256(wikiAbs);
+const wikiMtime = fs.statSync(wikiAbs).mtimeMs;
+const now = Date.now();
+
+// Update raw_to_wiki entry
+const existingRaw = manifest.raw_to_wiki[rawRel] ?? { wiki_pages: [] };
+const wikiPages = new Set(existingRaw.wiki_pages);
+wikiPages.add(wikiPageRel);
+
+manifest.raw_to_wiki[rawRel] = {
+  hash: rawHash,
+  modified: rawMtime,
+  ingested: now,
+  deferred: false,
+  wiki_pages: [...wikiPages],
+};
+
+// Update wiki_to_raw entry
+const existingWiki = manifest.wiki_to_raw[wikiPageRel] ?? { sources: [] };
+const sources = new Set(existingWiki.sources);
+sources.add(rawRel);
+
+manifest.wiki_to_raw[wikiPageRel] = {
+  hash: wikiHash,
+  last_compiled: wikiMtime,
+  sources: [...sources],
+  provenance_unknown: false,
+};
+
+manifest.last_ingestion = new Date(now).toISOString();
+
+saveManifest(absWikiPath, manifest);
+console.log(`[wiki-ingest-record] Recorded: ${rawRel} → ${wikiPageRel}`);

package/scripts/wiki-scan.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const VERSION = '0.1.0';
+
+function usage() {
+  console.error('Usage:');
+  console.error('  wiki-scan --version');
+  console.error('  wiki-scan --list <project-root>');
+  console.error('  wiki-scan --status <wiki-path>');
+  process.exit(1);
+}
+
+function loadManifest(wikiPath) {
+  const manifestPath = path.join(wikiPath, '.wiki-manifest.json');
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveManifest(wikiPath, manifest) {
+  const manifestPath = path.join(wikiPath, '.wiki-manifest.json');
+  const backupPath = path.join(wikiPath, '.wiki-manifest.backup.json');
+  const tmpPath = manifestPath + '.tmp';
+
+  // Backup current manifest before writing
+  if (fs.existsSync(manifestPath)) {
+    fs.copyFileSync(manifestPath, backupPath);
+  }
+
+  fs.writeFileSync(tmpPath, JSON.stringify(manifest, null, 2));
+  fs.renameSync(tmpPath, manifestPath);
+}
+
+function sha256(filePath) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
+function walkDir(dir, baseDir, results = []) {
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkDir(full, baseDir, results);
+    } else {
+      const rel = path.relative(baseDir, full).replace(/\\/g, '/');
+      const stat = fs.statSync(full);
+      results.push({ rel, full, mtimeMs: stat.mtimeMs });
+    }
+  }
+  return results;
+}
+
+function listWikis(projectRoot) {
+  const wikisDir = path.join(projectRoot, 'wikis');
+
+  if (!fs.existsSync(wikisDir)) return [];
+
+  const entries = fs.readdirSync(wikisDir, { withFileTypes: true });
+  const wikis = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const wikiPath = path.join(wikisDir, entry.name);
+    const manifest = loadManifest(wikiPath);
+    if (!manifest) continue;
+
+    wikis.push({
+      name: entry.name,
+      path: path.relative(projectRoot, wikiPath),
+      manifest,
+    });
+  }
+
+  return wikis;
+}
+
+function scanStatus(wikiPath) {
+  const absWikiPath = path.resolve(wikiPath);
+  const manifest = loadManifest(absWikiPath);
+
+  if (!manifest) {
+    console.error(`No manifest found at ${absWikiPath}/.wiki-manifest.json`);
+    process.exit(1);
+  }
+
+  const rawDir = path.join(absWikiPath, 'raw');
+  const wikiDir = path.join(absWikiPath, 'wiki');
+
+  // Walk raw/ — paths relative to wiki root (e.g. "raw/notes.md")
+  const rawFiles = walkDir(rawDir, absWikiPath);
+
+  // Walk wiki/ — paths relative to wiki root (e.g. "wiki/notes.md")
+  const wikiFiles = walkDir(wikiDir, absWikiPath);
+
+  // Build lookup: relPath → { hash, mtimeMs } from disk
+  // Use mtime-gating: if mtime matches manifest entry, reuse stored hash
+  const rawByPath = {};
+  for (const file of rawFiles) {
+    const entry = manifest.raw_to_wiki[file.rel];
+    if (entry && entry.modified === file.mtimeMs) {
+      rawByPath[file.rel] = { hash: entry.hash, mtimeMs: file.mtimeMs };
+    } else {
+      rawByPath[file.rel] = { hash: sha256(file.full), mtimeMs: file.mtimeMs };
+    }
+  }
+
+  const wikiByPath = {};
+  for (const file of wikiFiles) {
+    const entry = manifest.wiki_to_raw[file.rel];
+    if (entry && entry.last_compiled === file.mtimeMs) {
+      wikiByPath[file.rel] = { hash: entry.hash, mtimeMs: file.mtimeMs };
+    } else {
+      wikiByPath[file.rel] = { hash: sha256(file.full), mtimeMs: file.mtimeMs };
+    }
+  }
+
+  // Diff raw files vs manifest
+  const manifestRawPaths = new Set(Object.keys(manifest.raw_to_wiki));
+  const diskRawPaths = new Set(Object.keys(rawByPath));
+
+  const added = [];
+  const modified = [];
+  const deleted = [];
+  const renamed = [];
+  const deferred = [];
+
+  // Files on disk not in manifest → added candidates
+  const addedCandidates = [...diskRawPaths].filter(p => !manifestRawPaths.has(p));
+
+  // Files in manifest not on disk → deleted candidates
+  const deletedCandidates = [...manifestRawPaths].filter(p => !diskRawPaths.has(p));
+
+  // Rename detection: match deleted candidates to added candidates by hash
+  const deletedByHash = {};
+  for (const p of deletedCandidates) {
+    const h = manifest.raw_to_wiki[p].hash;
+    deletedByHash[h] = p;
+  }
+
+  const addedByHash = {};
+  for (const p of addedCandidates) {
+    const h = rawByPath[p].hash;
+    addedByHash[h] = p;
+  }
+
+  const renamedFromPaths = new Set();
+  const renamedToPaths = new Set();
+
+  for (const [hash, fromPath] of Object.entries(deletedByHash)) {
+    if (addedByHash[hash]) {
+      const toPath = addedByHash[hash];
+      renamed.push({ from: fromPath, to: toPath });
+      renamedFromPaths.add(fromPath);
+      renamedToPaths.add(toPath);
+
+      // Update manifest in-place for renamed entry
+      const entry = manifest.raw_to_wiki[fromPath];
+      delete manifest.raw_to_wiki[fromPath];
+      manifest.raw_to_wiki[toPath] = { ...entry, hash: rawByPath[toPath].hash, modified: rawByPath[toPath].mtimeMs };
+    }
+  }
+
+  // Remaining added/deleted after rename resolution
+  for (const p of addedCandidates) {
+    if (!renamedToPaths.has(p)) added.push(p);
+  }
+  for (const p of deletedCandidates) {
+    if (!renamedFromPaths.has(p)) deleted.push(p);
+  }
+
+  // Modified: same path, hash changed
+  for (const p of diskRawPaths) {
+    if (!manifestRawPaths.has(p)) continue; // handled above
+    const diskHash = rawByPath[p].hash;
+    const manifestEntry = manifest.raw_to_wiki[p];
+    if (diskHash !== manifestEntry.hash) {
+      modified.push(p);
+    } else if (manifestEntry.deferred) {
+      deferred.push(p);
+    }
+  }
+
+  // Wiki integrity: hash mismatch on compiled wiki files
+  const wikiIntegrity = [];
+  for (const [relPath, diskInfo] of Object.entries(wikiByPath)) {
+    const entry = manifest.wiki_to_raw[relPath];
+    if (entry && !entry.provenance_unknown && diskInfo.hash !== entry.hash) {
+      wikiIntegrity.push(relPath);
+    }
+  }
+
+  // Persist manifest if renames were detected
+  if (renamed.length > 0) {
+    saveManifest(absWikiPath, manifest);
+  }
+
+  const result = {
+    wiki_name: manifest.wiki_name,
+    added,
+    modified,
+    deleted,
+    renamed,
+    deferred,
+    wiki_integrity: wikiIntegrity,
+  };
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const [,, cmd, ...args] = process.argv;
+
+if (cmd === '--version') {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+if (cmd === '--list') {
+  const projectRoot = args[0];
+  if (!projectRoot) usage();
+  const wikis = listWikis(path.resolve(projectRoot));
+  console.log(JSON.stringify(wikis, null, 2));
+  process.exit(0);
+}
+
+if (cmd === '--status') {
+  const wikiPath = args[0];
+  if (!wikiPath) usage();
+  scanStatus(wikiPath);
+  process.exit(0);
+}
+
+usage();

package/scripts/wiki-status-html.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function usage() {
+  console.error('Usage:');
+  console.error('  wiki-status-html <wiki-path> <output-html-path> [--scan-json <scan-output.json>]');
+  process.exit(1);
+}
+
+function loadManifest(wikiPath) {
+  const manifestPath = path.join(wikiPath, '.wiki-manifest.json');
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    console.error(`Cannot read manifest at ${manifestPath}`);
+    process.exit(1);
+  }
+}
+
+function formatTs(ms) {
+  if (!ms) return '—';
+  return new Date(ms).toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC');
+}
+
+function shortHash(hash) {
+  return hash ? hash.slice(0, 8) : '—';
+}
+
+function getStatus(rawRel, entry, scanData) {
+  if (!scanData) {
+    if (!entry.ingested) return entry.deferred ? 'Deferred' : 'Pending';
+    return 'Synced';
+  }
+  if (scanData.added.includes(rawRel)) return 'Added';
+  if (scanData.modified.includes(rawRel)) return 'Modified';
+  if (scanData.deleted.includes(rawRel)) return 'Deleted';
+  if (scanData.renamed.some(r => r.from === rawRel || r.to === rawRel)) return 'Renamed';
+  if (entry && entry.deferred) return 'Deferred';
+  return 'Synced';
+}
+
+function statusBadge(status) {
+  const colors = {
+    Synced: '#22c55e',
+    Added: '#3b82f6',
+    Modified: '#f59e0b',
+    Deleted: '#ef4444',
+    Renamed: '#8b5cf6',
+    Deferred: '#94a3b8',
+    Pending: '#94a3b8',
+  };
+  const c = colors[status] || '#94a3b8';
+  return `<span class="badge" style="background:${c}">${status}</span>`;
+}
+
+function generateHtml(wikiPath, scanData) {
+  const absWikiPath = path.resolve(wikiPath);
+  const manifest = loadManifest(absWikiPath);
+  const generatedAt = new Date().toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC');
+
+  // Build rows: one per raw_to_wiki entry, plus scan-only added files not in manifest
+  const rows = [];
+  const manifestRawPaths = new Set(Object.keys(manifest.raw_to_wiki));
+
+  for (const [rawRel, entry] of Object.entries(manifest.raw_to_wiki)) {
+    const status = getStatus(rawRel, entry, scanData);
+    const wikiPages = entry.wiki_pages.join(', ') || '—';
+    const wikiHash = entry.wiki_pages.length > 0 && manifest.wiki_to_raw[entry.wiki_pages[0]]
+      ? shortHash(manifest.wiki_to_raw[entry.wiki_pages[0]].hash)
+      : '—';
+    rows.push({ rawRel, status, wikiPages, ingested: formatTs(entry.ingested), rawHash: shortHash(entry.hash), wikiHash });
+  }
+
+  // Add scan-only added files not yet in manifest
+  if (scanData) {
+    for (const rawRel of scanData.added) {
+      if (!manifestRawPaths.has(rawRel)) {
+        rows.push({ rawRel, status: 'Added', wikiPages: '—', ingested: '—', rawHash: '—', wikiHash: '—' });
+      }
+    }
+  }
+
+  // Summary counts
+  const counts = { Synced: 0, Added: 0, Modified: 0, Deleted: 0, Renamed: 0, Deferred: 0, Pending: 0 };
+  for (const r of rows) counts[r.status] = (counts[r.status] || 0) + 1;
+  const integrityCount = scanData ? scanData.wiki_integrity.length : 0;
+
+  const rowsHtml = rows.map(r => `
+    <tr data-status="${r.status}">
+      <td class="path">${r.rawRel}</td>
+      <td>${statusBadge(r.status)}</td>
+      <td class="path">${r.wikiPages}</td>
+      <td>${r.ingested}</td>
+      <td class="mono">${r.rawHash}</td>
+      <td class="mono">${r.wikiHash}</td>
+    </tr>`).join('\n');
+
+  const integrityRows = integrityCount > 0 ? `
+    <section class="integrity-section">
+      <h2>Wiki Integrity Warnings (${integrityCount})</h2>
+      <table>
+        <thead><tr><th>Wiki File</th><th>Note</th></tr></thead>
+        <tbody>
+          ${scanData.wiki_integrity.map(f => `<tr><td class="path">${f}</td><td>Hash mismatch — manually edited</td></tr>`).join('\n')}
+        </tbody>
+      </table>
+    </section>` : '';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${manifest.wiki_name} — Wiki Status</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #0f172a; color: #e2e8f0; padding: 2rem; }
+  h1 { font-size: 1.5rem; margin-bottom: 0.25rem; }
+  .meta { color: #94a3b8; font-size: 0.85rem; margin-bottom: 1.5rem; }
+  .summary { display: flex; gap: 1rem; flex-wrap: wrap; margin-bottom: 1.5rem; }
+  .summary-item { background: #1e293b; border-radius: 6px; padding: 0.5rem 1rem; font-size: 0.875rem; }
+  .summary-item span { font-weight: 700; }
+  .filters { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 1rem; }
+  .filter-btn { background: #1e293b; border: 1px solid #334155; color: #e2e8f0; padding: 0.35rem 0.75rem; border-radius: 4px; cursor: pointer; font-size: 0.8rem; }
+  .filter-btn.active { border-color: #60a5fa; color: #60a5fa; }
+  table { width: 100%; border-collapse: collapse; font-size: 0.85rem; }
+  th { text-align: left; padding: 0.6rem 0.75rem; background: #1e293b; color: #94a3b8; font-weight: 600; font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em; }
+  td { padding: 0.6rem 0.75rem; border-bottom: 1px solid #1e293b; }
+  tr:hover td { background: #1e293b; }
+  .path { font-family: monospace; font-size: 0.8rem; word-break: break-all; }
+  .mono { font-family: monospace; font-size: 0.8rem; color: #94a3b8; }
+  .badge { display: inline-block; padding: 0.2rem 0.5rem; border-radius: 3px; font-size: 0.75rem; font-weight: 600; color: #fff; }
+  .integrity-section { margin-top: 2rem; }
+  .integrity-section h2 { color: #fbbf24; font-size: 1rem; margin-bottom: 0.75rem; }
+  tr.hidden { display: none; }
+</style>
+</head>
+<body>
+<h1>${manifest.wiki_name}</h1>
+<p class="meta">
+  Last ingestion: ${manifest.last_ingestion ? manifest.last_ingestion.replace('T', ' ').replace(/\.\d+Z$/, ' UTC') : '—'} &nbsp;·&nbsp;
+  Generated: ${generatedAt}
+</p>
+
+<div class="summary">
+  <div class="summary-item"><span>${rows.length}</span> total</div>
+  ${Object.entries(counts).filter(([,v]) => v > 0).map(([k, v]) => `<div class="summary-item"><span>${v}</span> ${k}</div>`).join('\n  ')}
+  ${integrityCount > 0 ? `<div class="summary-item" style="border-left:3px solid #fbbf24"><span>${integrityCount}</span> integrity warnings</div>` : ''}
+</div>
+
+<div class="filters">
+  <button class="filter-btn active" onclick="filter('all')">All</button>
+  ${['Synced','Added','Modified','Deleted','Renamed','Deferred'].map(s => `<button class="filter-btn" onclick="filter('${s}')">${s}</button>`).join('\n  ')}
+</div>
+
+<table id="main-table">
+  <thead>
+    <tr>
+      <th>Raw File</th>
+      <th>Status</th>
+      <th>Wiki Page(s)</th>
+      <th>Last Ingested</th>
+      <th>Raw SHA256</th>
+      <th>Wiki SHA256</th>
+    </tr>
+  </thead>
+  <tbody>
+    ${rowsHtml}
+  </tbody>
+</table>
+
+${integrityRows}
+
+<script>
+let currentFilter = 'all';
+function filter(status) {
+  currentFilter = status;
+  document.querySelectorAll('.filter-btn').forEach(b => b.classList.toggle('active', b.textContent === (status === 'all' ? 'All' : status)));
+  document.querySelectorAll('#main-table tbody tr').forEach(tr => {
+    tr.classList.toggle('hidden', status !== 'all' && tr.dataset.status !== status);
+  });
+}
+</script>
+</body>
+</html>`;
+}
+
+const args = process.argv.slice(2);
+
+if (args.length < 2) usage();
+
+const wikiPath = args[0];
+const outputPath = args[1];
+
+let scanData = null;
+const scanJsonIdx = args.indexOf('--scan-json');
+if (scanJsonIdx !== -1 && args[scanJsonIdx + 1]) {
+  try {
+    scanData = JSON.parse(fs.readFileSync(args[scanJsonIdx + 1], 'utf8'));
+  } catch (e) {
+    console.error('Cannot read scan JSON:', e.message);
+    process.exit(1);
+  }
+}
+
+const html = generateHtml(wikiPath, scanData);
+fs.writeFileSync(outputPath, html);
+console.log(`[wiki-status-html] Report written to ${outputPath}`);

package/skill/MANIFEST-FORMAT.md

@@ -0,0 +1,49 @@
+# Manifest Format
+
+Each wiki has one manifest at `wikis/<name>/.wiki-manifest.json`. A backup is written to `.wiki-manifest.backup.json` before every mutation.
+
+## Schema
+
+```json
+{
+  "version": "1.0",
+  "wiki_name": "auditor",
+  "last_ingestion": null,
+  "raw_to_wiki": {
+    "raw/sub/paper.pdf": {
+      "hash": "sha256hex",
+      "modified": 1748600000000,
+      "ingested": 1748600000000,
+      "deferred": false,
+      "wiki_pages": ["wiki/concept-a.md"]
+    }
+  },
+  "wiki_to_raw": {
+    "wiki/concept-a.md": {
+      "hash": "sha256hex",
+      "last_compiled": 1748600000000,
+      "sources": ["raw/sub/paper.pdf"],
+      "provenance_unknown": false
+    }
+  }
+}
+```
+
+## Field Notes
+
+- `modified` / `last_compiled`: milliseconds since epoch (for fast mtime comparison)
+- `deferred: true`: file scanned and hash stored, but no LLM ingestion run yet
+- `provenance_unknown: true`: set by `rebuild-manifest` when wiki_to_raw entries are derived from disk scan without known source links
+- Both `raw_to_wiki` and `wiki_to_raw` paths are relative to the wiki root (`wikis/<name>/`)
+
+## Empty Manifest (written by `init`)
+
+```json
+{
+  "version": "1.0",
+  "wiki_name": "<name>",
+  "last_ingestion": null,
+  "raw_to_wiki": {},
+  "wiki_to_raw": {}
+}
+```

package/skill/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: wiki
+description: >
+  Multi-wiki sync layer for the Karpathy LLM Wiki pattern. Manages multiple independent
+  named wikis per project with sync observability, rename detection, and deferred ingestion.
+  Use when user types /wiki followed by a subcommand: init, use, list, status, ingest,
+  trace, report, recover, rebuild-manifest.
+---
+
+# Wiki Skill
+
+You are the `/wiki` command handler. Parse the first argument to determine the subcommand, then follow the instructions for that subcommand exactly.
+
+**Active wiki**: read from `.wiki-context` in the project root (the current working directory). Commands that require an active wiki must fail with this message if `.wiki-context` is missing or the named wiki no longer exists:
+> No active wiki. Run `/wiki use <name>` or `/wiki list` to see available wikis.
+
+See [MANIFEST-FORMAT.md](MANIFEST-FORMAT.md) for the manifest schema.
+
+---
+
+## `/wiki init <name>`
+
+1. If `<name>` is not provided: print `"Usage: /wiki init <name>"` and stop.
+2. If `wikis/<name>/` already exists: print `"Wiki '<name>' already exists. Use /wiki use <name> to activate it."` and stop.
+3. Create directories: `wikis/<name>/raw/` and `wikis/<name>/wiki/`
+4. Write `wikis/<name>/WIKI.md` using the content from [WIKI-TEMPLATE.md](WIKI-TEMPLATE.md), replacing `{{WIKI_NAME}}` with the actual name.
+5. Write `wikis/<name>/.wiki-manifest.json`:
+   ```json
+   {
+     "version": "1.0",
+     "wiki_name": "<name>",
+     "last_ingestion": null,
+     "raw_to_wiki": {},
+     "wiki_to_raw": {}
+   }
+   ```
+6. Print:
+   ```
+   Wiki '<name>' created at wikis/<name>/
+
+   Next steps:
+     1. Add source files to wikis/<name>/raw/
+     2. Run /wiki use <name> to activate this wiki
+     3. Run /wiki status to see what needs ingesting
+     4. Run /wiki ingest to compile your first wiki pages
+
+   Tip: git add wikis/<name>/ && git commit -m "Add <name> wiki"
+   ```
+
+---
+
+## `/wiki list`
+
+1. Run: `wiki-scan --list .`
+2. Parse the JSON array output.
+3. If the array is empty: print `"No wikis found. Run /wiki use <name> to create one."` and stop.
+4. For each wiki entry, print one line:
+   ```
+   <name>   (0 unsynced, 0 integrity warnings)
+   ```
+   Use the manifest's `raw_to_wiki` count for unsynced (files where `ingested` is null and `deferred` is false) and any wiki integrity warning data available.
+5. Mark the active wiki (from `.wiki-context`) with `[active]` suffix if set.
+
+---
+
+## `/wiki use <name>`
+
+1. If `<name>` is not provided: print `"Usage: /wiki use <name>"` and stop.
+2. Check that `wikis/<name>/.wiki-manifest.json` exists. If not: print `"Wiki '<name>' not found. Run /wiki list to see available wikis."` and stop.
+3. Write `<name>` to `.wiki-context` (overwrite if exists). The file should contain only the wiki name, no trailing whitespace.
+4. Print: `"Active wiki set to: <name>"`
+
+---
+
+## `/wiki status`
+
+### No active wiki (`.wiki-context` missing or empty)
+Run `wiki-scan --list .` and print a project-wide summary:
+```
+Wikis in this project:
+
+  auditor    0 unsynced
+  developer  2 unsynced
+
+Run /wiki use <name> to activate a wiki and see detailed status.
+```
+Count "unsynced" as entries in `raw_to_wiki` where `ingested` is null and `deferred` is false, plus any added/modified files visible in the manifest's stored state.
+
+### With active wiki
+1. Read `.wiki-context` to get `<name>`.
+2. Run: `wiki-scan --status wikis/<name>`
+3. Parse the JSON output. Fields: `wiki_name`, `added[]`, `modified[]`, `deleted[]`, `renamed[]` (objects with `from`/`to`), `deferred[]`, `wiki_integrity[]`.
+4. Format terminal report:
+   ```
+   Wiki: <name>
+
+   Raw changes
+     Added    (N): raw/file1.md, raw/file2.md
+     Modified (N): —
+     Deleted  (N): —
+     Renamed  (N): raw/old.md → raw/new.md
+
+   Deferred (N): —
+
+   Wiki integrity warnings (N): —
+   ```
+   Use `—` for empty lists. For renamed, format each pair as `<from> → <to>`.
+5. If `added + modified + deleted + renamed + deferred + wiki_integrity` are all zero: print `"Everything is in sync."` instead of the table.
+6. **Always show wiki integrity warnings as a separate section**, even when other raw changes exist. Never suppress them.
+
+---
+
+## `/wiki ingest [--defer]`
+
+Requires active wiki. Read `.wiki-context` for `<name>`.
+
+### With `--defer`
+
+1. Run: `wiki-scan --status wikis/<name>`
+2. Collect all files in `added` and `modified` from the scan output.
+3. If none: print `"Nothing to defer. Run /wiki status to check."` and stop.
+4. For each file, run: `wiki-ingest-record wikis/<name> --defer <file>`
+5. Print:
+   ```
+   Deferred N file(s). No tokens consumed.
+   Run /wiki ingest (without --defer) when ready to process them.
+   ```
+6. **Zero LLM calls** — this entire command is pure script execution. Do not read or process any raw files.
+
+### Without `--defer`
+
+1. Run: `wiki-scan --status wikis/<name>`
+2. Collect files to ingest: all in `added` + `modified` + any entries in the manifest where `deferred: true`.
+3. If `wiki_integrity` warnings exist, address them **first** (see Wiki Integrity Resolution below) before proceeding.
+4. If nothing to ingest after integrity resolution: print `"Nothing to ingest. Everything is in sync."` and stop.
+5. Present the file list:
+   ```
+   Ready to ingest N file(s) into wiki '<name>':
+     - raw/file1.md
+     - raw/file2.md
+   Proceed? (y/n)
+   ```
+6. On `n`: stop.
+7. For each file to ingest:
+   a. Read the file at `wikis/<name>/<raw-file>`
+   b. Read `wikis/<name>/WIKI.md` for domain conventions
+   c. Determine the wiki page path: `wiki/<basename-without-ext>.md` — if a page already exists for this raw file in the manifest (`wiki_pages`), use that path instead
+   d. Write or update the wiki page at `wikis/<name>/<wiki-page>` based on the raw file content and WIKI.md conventions. Include frontmatter:
+      ```yaml
+      ---
+      sources:
+        - <raw-file-relpath>
+      last_compiled: <ISO timestamp>
+      ---
+      ```
+   e. Run: `wiki-ingest-record wikis/<name> <raw-file> <wiki-page>`
+   f. Print: `✓ <raw-file> → <wiki-page>`
+8. Print: `"Ingested N file(s). Run /wiki status to verify."`
+
+### Wiki Integrity Resolution
+
+When `wiki-scan --status` returns entries in `wiki_integrity`:
+1. Print: `"Wiki integrity warning: the following wiki files have been manually modified (hash mismatch):"`
+2. List the affected files.
+3. For each affected file, ask: `"Was this edit to <wiki-page> intentional? (y/n)"`
+   - `y` → run `wiki-ingest-record wikis/<name> <matching-raw-file> --update-hash-only` (keeps edit, updates stored hash)
+   - `n` → re-ingest the source raw file: read raw, rewrite wiki page, run `wiki-ingest-record` normally
+4. Never auto-resolve. Always ask.
+
+---
+
+## `/wiki trace <file>`
+
+Requires active wiki.
+
+1. Read `.wiki-context` for `<name>`.
+2. Load `wikis/<name>/.wiki-manifest.json`.
+3. Normalize `<file>`: strip leading `wikis/<name>/` prefix if present. The remaining path should start with `raw/` or `wiki/`.
+4. Determine direction:
+   - If path starts with `raw/`: look up `manifest.raw_to_wiki[<file>]`
+   - If path starts with `wiki/`: look up `manifest.wiki_to_raw[<file>]`
+   - If neither matches: try both directions
+5. If not found in manifest: print `"<file> not found in manifest. Has it been ingested?"` and stop.
+6. Print:
+
+**Raw → Wiki direction:**
+```
+Tracing: raw/transformers.md
+
+  Status:     Synced                   (or: Deferred / Pending)
+  Ingested:   2026-05-30 12:00:00 UTC  (or: —)
+  Raw hash:   a1b2c3d4
+  Wiki pages:
+    wiki/transformers.md
+      Hash:     e5f6g7h8
+      Compiled: 2026-05-30 12:00:00 UTC
+      Sources:  raw/transformers.md
+```
+
+**Wiki → Raw direction:**
+```
+Tracing: wiki/transformers.md
+
+  Hash:      e5f6g7h8
+  Compiled:  2026-05-30 12:00:00 UTC
+  Sources:
+    raw/transformers.md
+      Hash:     a1b2c3d4
+      Ingested: 2026-05-30 12:00:00 UTC
+```
+
+Use `—` for null/missing values. Format timestamps as `YYYY-MM-DD HH:MM:SS UTC`.
+
+---
+
+## `/wiki report`
+
+Requires active wiki.
+
+1. Read `.wiki-context` for `<name>`.
+2. Run: `wiki-scan --status wikis/<name>`
+3. Write the scan JSON output to a temp file at `/tmp/wiki-scan-<name>.json`
+4. Run: `wiki-status-html wikis/<name> /tmp/wiki-report-<name>.html --scan-json /tmp/wiki-scan-<name>.json`
+5. Open the HTML file in the default browser:
+   - Linux: `xdg-open /tmp/wiki-report-<name>.html`
+   - macOS: `open /tmp/wiki-report-<name>.html`
+   - If `open`/`xdg-open` fails: print the path instead: `"Report generated: /tmp/wiki-report-<name>.html"`
+6. Print: `"Report generated: /tmp/wiki-report-<name>.html"`
+
+---
+
+## `/wiki recover manifest`
+
+Requires active wiki.
+
+1. Check `wikis/<name>/.wiki-manifest.backup.json` exists. If not: print `"No backup found at wikis/<name>/.wiki-manifest.backup.json. Cannot recover."` and stop.
+2. Parse the backup file and extract `last_ingestion` and entry counts.
+3. Print:
+   ```
+   Backup found:
+     Last ingestion: <timestamp or "—">
+     Raw entries:    N
+     Wiki entries:   M
+   ```
+4. Ask: `"Restore manifest from this backup? (y/n)"`
+5. On `n`: print `"Aborted."` and stop.
+6. On `y`: copy backup over manifest (`wikis/<name>/.wiki-manifest.backup.json` → `wikis/<name>/.wiki-manifest.json`).
+7. Print: `"Manifest restored from backup."`
+
+---
+
+## `/wiki rebuild-manifest`
+
+Requires active wiki.
+
+1. Print:
+   ```
+   WARNING: This will re-derive the manifest from raw/ and wiki/ file hashes.
+   Wiki provenance (source→page links) will be lost and marked as unknown.
+   This cannot be undone unless you have a git backup.
+   ```
+2. Ask: `"Proceed with manifest rebuild? (y/n)"`
+3. On `n`: print `"Aborted."` and stop.
+4. On `y`:
+   a. Write backup of current manifest first (copy to `.wiki-manifest.backup.json`)
+   b. Walk `wikis/<name>/raw/` recursively, compute SHA-256 for every file
+   c. Walk `wikis/<name>/wiki/` recursively, compute SHA-256 for every file
+   d. Build new manifest:
+      - `raw_to_wiki`: one entry per raw file with `{hash, modified: <mtimeMs>, ingested: null, deferred: false, wiki_pages: []}`
+      - `wiki_to_raw`: one entry per wiki file with `{hash, last_compiled: null, sources: [], provenance_unknown: true}`
+   e. Write new manifest atomically (write to `.tmp`, rename over manifest)
+5. Print:
+   ```
+   Manifest rebuilt from disk.
+   N raw files, M wiki files found.
+   All wiki provenance marked as unknown.
+
+   Run /wiki ingest to re-establish source→page links.
+   ```
+
+---
+
+## `/wiki recover schema`
+
+Requires active wiki.
+
+1. Print:
+   ```
+   WARNING: This will overwrite wikis/<name>/WIKI.md with the default template.
+   Any customizations you have made to this file will be lost.
+   ```
+2. Ask: `"Overwrite WIKI.md with the default template? (y/n)"`
+3. On `n`: print `"Aborted."` and stop.
+4. On `y`: write the content from [WIKI-TEMPLATE.md](WIKI-TEMPLATE.md) to `wikis/<name>/WIKI.md`, replacing `{{WIKI_NAME}}` with the actual wiki name.
+5. Print:
+   ```
+   WIKI.md reset to default template.
+   Customize it to describe your wiki's domain and conventions.
+   ```
+
+---
+
+## Unknown subcommand
+
+Print:
+```
+Unknown subcommand. Available commands:
+  /wiki init <name>       Create a new wiki
+  /wiki use <name>        Set the active wiki
+  /wiki list              List all wikis
+  /wiki status            Show sync status
+  /wiki ingest [--defer]  Ingest unsynced files
+  /wiki trace <file>      Show file provenance
+  /wiki report            Generate HTML report
+  /wiki recover manifest  Restore manifest from backup
+  /wiki rebuild-manifest  Re-derive manifest from disk
+  /wiki recover schema    Reset WIKI.md to default template
+```

package/skill/WIKI-TEMPLATE.md

@@ -0,0 +1,36 @@
+# {{WIKI_NAME}} Wiki
+
+This wiki covers: **[describe the knowledge domain here]**
+
+## How This Wiki Works
+
+Source files live in `raw/`. When you run `/wiki ingest`, the AI reads each raw file and compiles it into a structured wiki page under `wiki/`. Every wiki page records its source files in frontmatter so provenance is always traceable.
+
+## Wiki Page Format
+
+Each compiled wiki page should use this frontmatter:
+
+```yaml
+---
+sources:
+  - raw/filename.md
+last_compiled: YYYY-MM-DDTHH:MM:SSZ
+---
+```
+
+## Domain Conventions
+
+[Describe what belongs in this wiki, how concepts should be structured, any domain-specific terminology, and what level of detail wiki pages should have.]
+
+## What to Include
+
+- Key concepts and their definitions
+- Relationships between concepts
+- Important facts, decisions, or findings from source documents
+- Cross-references between wiki pages where relevant
+
+## What to Exclude
+
+- Verbatim copies of source documents
+- Formatting noise or metadata from source files
+- Duplicate information already covered in another wiki page