llm-wikis 0.2.1 → 0.2.2

package/README.md

@@ -0,0 +1,128 @@
+# llm-wikis
+
+Multi-wiki sync observability for the [Karpathy LLM Wiki](https://karpathy.ai/zero-to-hero.html) pattern.
+
+![llm-wikis banner](docs/assets/github-banner.png)
+
+---
+
+## What is this?
+
+Karpathy's LLM Wiki pattern: instead of RAG querying raw chunks at runtime, an AI agent reads your source files and incrementally compiles them into a structured, persistent, interlinked Markdown wiki. It solves RAG's statelessness and chunk-boundary noise — the AI owns the overhead, you own the sourcing and querying.
+
+**llm-wikis** adds the sync layer that the pattern ships without:
+
+- **Multiple independent wikis per project** — each covering a different knowledge domain, under a single `/wikis` command surface
+- **Sync visibility** — see exactly what's changed, added, deleted, or renamed before any tokens are spent
+- **Rename detection** — file moves resolved from hash comparison, zero LLM tokens
+- **Deferred ingestion** — flag files for later with `--later`, no surprise token costs
+- **Provenance tracking** — bidirectional manifest linking every `raw/` file to the `wiki/` pages it produced
+- **Wiki integrity auditing** — detect and resolve manually-edited wiki files before they silently diverge
+
+Works with **Claude Code**, **Gemini CLI**, and **Codex** via a neutral `WIKI.md` schema (not hardcoded to `CLAUDE.md`).
+
+---
+
+## Install
+
+```bash
+npm install -g llm-wikis
+```
+
+This installs three CLI scripts and places the skill file at `~/.claude/skills/wikis/`.
+
+---
+
+## Slash commands
+
+Use `/wikis` directly in Claude Code (or any supported LLM CLI):
+
+| Command | Description |
+|---|---|
+| `/wikis init <name>` | Create a new wiki at `wikis/<name>/` |
+| `/wikis use <name>` | Set the active wiki |
+| `/wikis list` | List all wikis with sync state |
+| `/wikis status` | Show what's changed since last ingest |
+| `/wikis ingest` | Ingest unsynced raw files into wiki pages |
+| `/wikis ingest --later` | Mark files for later — zero token usage |
+| `/wikis trace <file>` | Show bidirectional provenance for any file |
+| `/wikis report` | Generate a filterable HTML provenance report |
+| `/wikis recover manifest` | Restore manifest from backup |
+| `/wikis rebuild-manifest` | Re-derive manifest from disk scan |
+| `/wikis recover schema` | Reset `WIKI.md` to the default template |
+
+---
+
+## CLI scripts
+
+Three deterministic scripts are available directly (used internally by the skill, but callable standalone):
+
+```bash
+# List all wikis in a project
+wikis scan --list <project-root>
+
+# Show sync status for a wiki
+wikis scan --status <wiki-path>
+
+# Record a raw → wiki ingestion in the manifest
+wikis record <wiki-path> <raw-file> <wiki-page>
+
+# Generate a static HTML report
+wikis report <wiki-path> <output.html>
+```
+
+---
+
+## Project structure
+
+Running `/wikis init` creates:
+
+```
+project/
+  wikis/
+    <name>/
+      raw/          ← drop source files here (PDFs, notes, docs)
+      wiki/         ← compiled wiki pages live here
+      WIKI.md       ← schema: domain conventions for the LLM
+      .wiki-manifest.json
+      .wiki-manifest.backup.json
+  .wiki-context     ← active wiki name (set by /wikis use)
+```
+
+Multiple wikis are fully independent — different raw sources, different wiki pages, separate manifests.
+
+---
+
+## Manifest
+
+Each wiki has a bidirectional manifest tracking every `raw/ → wiki/` relationship:
+
+```json
+{
+  "version": "1.0",
+  "wiki_name": "auditor",
+  "last_ingestion": "2026-05-30T12:00:00Z",
+  "raw_to_wiki": {
+    "raw/paper.pdf": {
+      "hash": "sha256...",
+      "ingested": 1748600000000,
+      "deferred": false,
+      "wiki_pages": ["wiki/concept-a.md"]
+    }
+  },
+  "wiki_to_raw": {
+    "wiki/concept-a.md": {
+      "hash": "sha256...",
+      "sources": ["raw/paper.pdf"]
+    }
+  }
+}
+```
+
+The LLM never writes the manifest directly — only the deterministic scripts do, atomically, with a backup before every write.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wikis",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Multi-wiki sync observability for the Karpathy LLM Wiki pattern",
   "license": "MIT",
   "bin": {

package/scripts/wiki-ingest-record.js

@@ -9,7 +9,7 @@ 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>');
+  console.error('  wiki-ingest-record <wiki-path> --later <raw-file-relpath>');
   process.exit(1);
 }
 
@@ -43,8 +43,8 @@ if (!wikiPath || !arg2) usage();
 
 const absWikiPath = path.resolve(wikiPath);
 
-// Mode: --defer <raw-file>
-if (arg2 === '--defer') {
+// Mode: --later <raw-file>
+if (arg2 === '--later') {
   const rawRel = arg3;
   if (!rawRel) usage();
 

package/scripts/wiki-scan.js

@@ -5,7 +5,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 
-const VERSION = '0.2.1';
+const VERSION = '0.2.2';
 
 function usage() {
   console.error('Usage:');

package/scripts/wikis.js

@@ -4,7 +4,7 @@
 const { execFileSync } = require('child_process');
 const path = require('path');
 
-const VERSION = '0.2.1';
+const VERSION = '0.2.2';
 
 const HELP = `
 llm-wikis v${VERSION}
@@ -22,7 +22,7 @@ Slash commands (Claude Code / Gemini CLI / Codex):
   /wikis use <name>         Set the active wiki
   /wikis list               List all wikis
   /wikis status             Show sync status
-  /wikis ingest [--defer]   Ingest unsynced files
+  /wikis ingest [--later]   Ingest unsynced files
   /wikis trace <file>       Show file provenance
   /wikis report             Generate HTML report
   /wikis recover manifest   Restore manifest from backup

package/skill/SKILL.md

@@ -110,24 +110,24 @@ Count "unsynced" as entries in `raw_to_wiki` where `ingested` is null and `defer
 
 ---
 
-## `/wikis ingest [--defer]`
+## `/wikis ingest [--later]`
 
 Requires active wiki. Read `.wiki-context` for `<name>`.
 
-### With `--defer`
+### With `--later`
 
 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 /wikis status to check."` and stop.
-4. For each file, run: `wiki-ingest-record wikis/<name> --defer <file>`
+4. For each file, run: `wiki-ingest-record wikis/<name> --later <file>`
 5. Print:
    ```
    Deferred N file(s). No tokens consumed.
-   Run /wikis ingest (without --defer) when ready to process them.
+   Run /wikis ingest (without --later) 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`
+### Without `--later`
 
 1. Run: `wiki-scan --status wikis/<name>`
 2. Collect files to ingest: all in `added` + `modified` + any entries in the manifest where `deferred: true`.
@@ -309,7 +309,7 @@ Unknown subcommand. Available commands:
   /wikis use <name>        Set the active wiki
   /wikis list              List all wikis
   /wikis status            Show sync status
-  /wikis ingest [--defer]  Ingest unsynced files
+  /wikis ingest [--later]  Ingest unsynced files
   /wikis trace <file>      Show file provenance
   /wikis report            Generate HTML report
   /wikis recover manifest  Restore manifest from backup