llm-wikis 0.1.0 → 0.2.1

package/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Verify tag matches package version
+        run: |
+          PKG_VERSION="v$(node -p "require('./package.json').version")"
+          TAG_VERSION="${GITHUB_REF_NAME}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Tag $TAG_VERSION does not match package version $PKG_VERSION"
+            exit 1
+          fi
+
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "llm-wikis",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Multi-wiki sync observability for the Karpathy LLM Wiki pattern",
   "license": "MIT",
   "bin": {
+    "wikis": "scripts/wikis.js",
     "wiki-scan": "scripts/wiki-scan.js",
     "wiki-ingest-record": "scripts/wiki-ingest-record.js",
     "wiki-status-html": "scripts/wiki-status-html.js"

package/scripts/wiki-scan.js

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

package/scripts/wikis.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const VERSION = '0.2.1';
+
+const HELP = `
+llm-wikis v${VERSION}
+
+Usage: wikis <command> [args]
+
+Commands:
+  wikis scan   --list <project-root>   List all wikis in a project
+  wikis scan   --status <wiki-path>    Show sync status for a wiki
+  wikis record <wiki-path> ...         Record an ingestion in the manifest
+  wikis report <wiki-path> <out.html>  Generate HTML status report
+
+Slash commands (Claude Code / Gemini CLI / Codex):
+  /wikis init <name>        Create a new wiki
+  /wikis use <name>         Set the active wiki
+  /wikis list               List all wikis
+  /wikis status             Show sync status
+  /wikis ingest [--defer]   Ingest unsynced files
+  /wikis trace <file>       Show file provenance
+  /wikis report             Generate HTML report
+  /wikis recover manifest   Restore manifest from backup
+  /wikis rebuild-manifest   Re-derive manifest from disk
+  /wikis recover schema     Reset WIKI.md to default template
+
+Install the Claude Code skill:
+  npm install -g llm-wikis   (skill auto-installs to ~/.claude/skills/wikis/)
+`.trim();
+
+const [,, cmd, ...args] = process.argv;
+
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (cmd === '--version' || cmd === '-v') {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+const scriptsDir = path.join(__dirname);
+
+const dispatch = {
+  scan: 'wiki-scan.js',
+  record: 'wiki-ingest-record.js',
+  report: 'wiki-status-html.js',
+};
+
+if (dispatch[cmd]) {
+  try {
+    execFileSync(process.execPath, [path.join(scriptsDir, dispatch[cmd]), ...args], { stdio: 'inherit' });
+  } catch (e) {
+    process.exit(e.status ?? 1);
+  }
+} else {
+  console.error(`Unknown command: ${cmd}\nRun "wikis --help" for usage.`);
+  process.exit(1);
+}

package/skill/SKILL.md

@@ -1,27 +1,27 @@
 ---
-name: wiki
+name: wikis
 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,
+  Use when user types /wikis 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.
+You are the `/wikis` 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.
+> No active wiki. Run `/wikis use <name>` or `/wikis list` to see available wikis.
 
 See [MANIFEST-FORMAT.md](MANIFEST-FORMAT.md) for the manifest schema.
 
 ---
 
-## `/wiki init <name>`
+## `/wikis 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.
+1. If `<name>` is not provided: print `"Usage: /wikis init <name>"` and stop.
+2. If `wikis/<name>/` already exists: print `"Wiki '<name>' already exists. Use /wikis 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`:
@@ -40,20 +40,20 @@ See [MANIFEST-FORMAT.md](MANIFEST-FORMAT.md) for the manifest schema.
 
    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
+     2. Run /wikis use <name> to activate this wiki
+     3. Run /wikis status to see what needs ingesting
+     4. Run /wikis ingest to compile your first wiki pages
 
    Tip: git add wikis/<name>/ && git commit -m "Add <name> wiki"
    ```
 
 ---
 
-## `/wiki list`
+## `/wikis 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.
+3. If the array is empty: print `"No wikis found. Run /wikis use <name> to create one."` and stop.
 4. For each wiki entry, print one line:
    ```
    <name>   (0 unsynced, 0 integrity warnings)
@@ -63,16 +63,16 @@ See [MANIFEST-FORMAT.md](MANIFEST-FORMAT.md) for the manifest schema.
 
 ---
 
-## `/wiki use <name>`
+## `/wikis 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.
+1. If `<name>` is not provided: print `"Usage: /wikis use <name>"` and stop.
+2. Check that `wikis/<name>/.wiki-manifest.json` exists. If not: print `"Wiki '<name>' not found. Run /wikis 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`
+## `/wikis status`
 
 ### No active wiki (`.wiki-context` missing or empty)
 Run `wiki-scan --list .` and print a project-wide summary:
@@ -82,7 +82,7 @@ Wikis in this project:
   auditor    0 unsynced
   developer  2 unsynced
 
-Run /wiki use <name> to activate a wiki and see detailed status.
+Run /wikis 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.
 
@@ -110,7 +110,7 @@ Count "unsynced" as entries in `raw_to_wiki` where `ingested` is null and `defer
 
 ---
 
-## `/wiki ingest [--defer]`
+## `/wikis ingest [--defer]`
 
 Requires active wiki. Read `.wiki-context` for `<name>`.
 
@@ -118,12 +118,12 @@ Requires active wiki. Read `.wiki-context` for `<name>`.
 
 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.
+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>`
 5. Print:
    ```
    Deferred N file(s). No tokens consumed.
-   Run /wiki ingest (without --defer) when ready to process them.
+   Run /wikis 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.
 
@@ -155,7 +155,7 @@ Requires active wiki. Read `.wiki-context` for `<name>`.
       ```
    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."`
+8. Print: `"Ingested N file(s). Run /wikis status to verify."`
 
 ### Wiki Integrity Resolution
 
@@ -169,7 +169,7 @@ When `wiki-scan --status` returns entries in `wiki_integrity`:
 
 ---
 
-## `/wiki trace <file>`
+## `/wikis trace <file>`
 
 Requires active wiki.
 
@@ -213,23 +213,23 @@ Use `—` for null/missing values. Format timestamps as `YYYY-MM-DD HH:MM:SS UTC
 
 ---
 
-## `/wiki report`
+## `/wikis 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`
+3. Write the scan JSON output to a temp file at `/tmp/wikis-scan-<name>.json`
+4. Run: `wiki-status-html wikis/<name> /tmp/wikis-report-<name>.html --scan-json /tmp/wikis-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"`
+   - Linux: `xdg-open /tmp/wikis-report-<name>.html`
+   - macOS: `open /tmp/wikis-report-<name>.html`
+   - If `open`/`xdg-open` fails: print the path instead: `"Report generated: /tmp/wikis-report-<name>.html"`
+6. Print: `"Report generated: /tmp/wikis-report-<name>.html"`
 
 ---
 
-## `/wiki recover manifest`
+## `/wikis recover manifest`
 
 Requires active wiki.
 
@@ -249,7 +249,7 @@ Requires active wiki.
 
 ---
 
-## `/wiki rebuild-manifest`
+## `/wikis rebuild-manifest`
 
 Requires active wiki.
 
@@ -275,12 +275,12 @@ Requires active wiki.
    N raw files, M wiki files found.
    All wiki provenance marked as unknown.
 
-   Run /wiki ingest to re-establish source→page links.
+   Run /wikis ingest to re-establish source→page links.
    ```
 
 ---
 
-## `/wiki recover schema`
+## `/wikis recover schema`
 
 Requires active wiki.
 
@@ -305,14 +305,14 @@ Requires active wiki.
 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
+  /wikis init <name>       Create a new wiki
+  /wikis use <name>        Set the active wiki
+  /wikis list              List all wikis
+  /wikis status            Show sync status
+  /wikis ingest [--defer]  Ingest unsynced files
+  /wikis trace <file>      Show file provenance
+  /wikis report            Generate HTML report
+  /wikis recover manifest  Restore manifest from backup
+  /wikis rebuild-manifest  Re-derive manifest from disk
+  /wikis recover schema    Reset WIKI.md to default template
 ```