repo-nexus 0.2.6 → 0.2.9

package/README.md

@@ -9,13 +9,6 @@
 
 A **simple, lightweight companion tool** for multi-repo workflows. It links multiple independent repositories and shares universal AI instructions (like `AGENTS.md`) using standard Unix symlinks — **without Git submodules, monorepo migrations, or complex setup**.
 
-- **No Git Submodules or Nested Git Friction**: Keep your repositories completely independent. No detached HEADs, no `.gitmodules`, and no merge conflicts between repos.
-- **A Lean Companion, Not a Workspace Replacer**: It does not replace your editor, terminal, build tools, or package manager. It is a tiny (~20 KB) helper that seamlessly complements your existing workflow.
-- **Unified Workspace for AI Coding Assistants**: Open one folder to give Cursor, Claude Code, GitHub Copilot, or Antigravity complete cross-repo visibility.
-- **Single Source of Truth for AI Guidelines**: Share and sync `AGENTS.md`, Copilot instructions (`.github/copilot-instructions.md`), Cursor rules (`.cursorrules`), Claude instructions (`CLAUDE.md`), and custom prompts across all projects.
-- **Zero Dependencies**: Pure POSIX shell CLI (`rnex`). Works out of the box with zero external runtimes required.
-A **simple, lightweight companion tool** for multi-repo workflows. It links multiple independent repositories and shares universal AI instructions (like `AGENTS.md`) using standard Unix symlinks — **without Git submodules, monorepo migrations, or complex setup**.
-
 - **No Git Submodules or Nested Git Friction**: Keep your repositories completely independent. No detached HEADs, no `.gitmodules`, and no merge conflicts between repos.
 - **A Lean Companion, Not a Workspace Replacer**: It does not replace your editor, terminal, build tools, or package manager. It is a tiny (~20 KB) helper that seamlessly complements your existing workflow.
 - **Unified Workspace for AI Coding Assistants**: Open one folder to give Cursor, Claude Code, GitHub Copilot, or Antigravity complete cross-repo visibility.
@@ -26,14 +19,23 @@ A **simple, lightweight companion tool** for multi-repo workflows. It links mult
 
 ---
 
-## What Repo Nexus Is (and What It Isn't)
-
-| What It Is | What It Isn't |
-| :--- | :--- |
-| **A lightweight companion utility** (~20 KB POSIX script). | **NOT a replacement for your workspace or tools.** It doesn't replace VS Code, Cursor, JetBrains, or your terminal. |
-| **A simple symlink manager** that groups existing repos into one folder for convenience. | **NOT a build tool or monorepo orchestrator.** It doesn't manage builds or replace tools like Nx, Turborepo, Cargo, or Gradle. |
-| **Zero Git friction.** Repositories remain normal, autonomous Git repos. | **NOT Git submodules or subtrees.** No `.gitmodules` files, no detached HEADs, no commit coordination lock-in. |
-| **Non-invasive.** If you delete the workspace, your repos remain completely untouched. | **NOT a proprietary platform.** No background daemons, no database, no vendor lock-in. |
+## Table of Contents
+
+- [What Repo Nexus Is (and What It Isn't)](#what-repo-nexus-is-and-what-it-isnt)
+- [How It Works: The Two Symlink Flows](#how-it-works-the-two-symlink-flows)
+- [Key Principles](#key-principles)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Everyday Usage](#everyday-usage)
+- [Plugins & AI Context Packs](#plugins--ai-context-packs)
+- [Workspace Configuration (`rnex.yaml`)](#workspace-configuration-rnexyaml)
+- [CLI Command Reference](#cli-command-reference)
+- [Operating on External Workspaces via `--config`](#operating-on-external-workspaces-via---config)
+- [Supported AI Configuration Files](#supported-ai-configuration-files)
+- [Project Structure](#project-structure)
+- [Running Tests](#running-tests)
+- [Frequently Asked Questions (FAQ)](docs/FAQ.md)
+- [License](#license)
 
 ---
 
@@ -81,19 +83,14 @@ A **simple, lightweight companion tool** for multi-repo workflows. It links mult
 
 ## Key Principles
 
-1. **No Git Submodules (Complete Repository Autonomy)**:
-   Member repositories are never converted into Git submodules or subtrees. Each repository keeps its own standalone Git history, remotes, branches, and commits. `rnex` simply links them on your local filesystem.
 1. **No Git Submodules (Complete Repository Autonomy)**:
    Member repositories are never converted into Git submodules or subtrees. Each repository keeps its own standalone Git history, remotes, branches, and commits. `rnex` simply links them on your local filesystem.
 
-2. **Symlink Write-Through**:
-   Symlinks are transparent pointers resolved by your OS. When you or an AI agent edit `repos/backend/src/index.ts`, the OS resolves the link and writes directly to the source repository on disk.
 2. **Symlink Write-Through**:
    Symlinks are transparent pointers resolved by your OS. When you or an AI agent edit `repos/backend/src/index.ts`, the OS resolves the link and writes directly to the source repository on disk.
 
 3. **Single Source of Truth for AI Context**:
    Edit `AGENTS.md` once in Repo Nexus, and changes immediately reflect across all member repositories.
-   Edit `AGENTS.md` once in Repo Nexus, and changes immediately reflect across all member repositories.
 
 4. **Dynamic Workspace Scope**:
    Easily show or hide member repos from the active workspace without modifying disk contents.
@@ -113,25 +110,10 @@ npm install -g repo-nexus
 
 ### Option 2: Via GitHub Packages
 
-```bash
-npm install -g @nu-nenoi/repo-nexus --registry=https://npm.pkg.github.com
-```
-Install `rnex` via npm, GitHub Packages, or the zero-dependency native installer:
-
-### Option 1: Via npm (Recommended)
-
-```bash
-npm install -g repo-nexus
-```
-*(Installs both `repo-nexus` and `rnex` commands globally, or run via `npx repo-nexus init`)*
-
-### Option 2: Via GitHub Packages
-
 ```bash
 npm install -g @nu-nenoi/repo-nexus --registry=https://npm.pkg.github.com
 ```
 
-### Option 3: Native Installer (Zero Dependencies)
 ### Option 3: Native Installer (Zero Dependencies)
 
 Clone the repository and run the built-in installer:
@@ -143,7 +125,6 @@ cd repo-nexus
 ```
 *(Installs `rnex` and `repo-nexus` symlinks into `~/.local/bin`, or pass a custom directory like `./rnex install /usr/local/bin`)*
 
-### Option 4: Shell Alias
 ### Option 4: Shell Alias
 
 Add to your `~/.zshrc` or `~/.bashrc`:
@@ -219,14 +200,24 @@ rnex plugin disable karpathy-llm
 ```
 
 ### Built-in Plugin: `karpathy-llm`
-The `karpathy-llm` plugin packages Andrej Karpathy's verified LLM agent design patterns and context engineering principles:
+The `karpathy-llm` plugin packages Andrej Karpathy's verified LLM agent design patterns, context engineering principles, and the autonomous **Karpathy LLM Wiki** architecture (based on [`setup-karpathy-wiki.md`](https://github.com/nu-nenoi/ai-toolkit/blob/main/prompts/setup-karpathy-wiki.md), available locally in `toolkit/prompts/setup-karpathy-wiki.md`):
+* **Step 0 — Configuration Interview:** Guides setup decisions including target agent instruction file (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/wiki.mdc`, etc.), wiki purpose (codebase, second brain, research, content archive), organization layout (flat vs structured), and automation enablement.
 * **The 4 Cardinal Agent Rules** (`.agents/rules/KARPATHY_RULES.md`):
   1. *Think Before Coding:* Formulate explicit assumptions, boundary checks, and trade-offs before writing code.
   2. *Simplicity First:* Minimal abstractions, readable implementations, zero speculative boilerplate.
   3. *Surgical Changes:* Minimal blast radius, preserved comments/docstrings, and tight diffs.
   4. *Goal-Driven Execution:* Upfront verification criteria, automated tests, and diff inspection.
-* **Multi-Repo Context Engineering:** Guidelines for AI agents respecting member repo autonomy and symlink write-through semantics.
-* **LLM Wiki Knowledge Pattern** (`docs/LLM_WIKI.sample.md`): Persistent, indexed multi-repo architecture documentation that compounds across agent sessions.
+* **Autonomous Karpathy LLM Wiki Knowledge Architecture:**
+  * **Intake (`/raw/`):** Append-only intake for unmodified source documents.
+  * **Curated Knowledge Base (`/wiki/`):** Interlinked atomic markdown pages with typed YAML frontmatter relations (`sources`, `related`, `extends`, `contradicts`, `mentioned_in`).
+  * **Control Index (`/wiki/index.md`):** Master navigation index with `lint_trigger: enabled|disabled` toggle.
+  * **Rolling Context (`/wiki/hot.md`):** ~500-word quick-orient context cache for AI agents.
+  * **Operation Log (`/wiki/_log.md`):** Append-only audit trail of ingest and lint operations.
+  * **Session Counter (`/wiki/.lint_trigger_counter`):** Machine-local state tracking session activity (gitignored).
+* **Autonomous Lint Trigger (`scripts/wiki-lint-trigger.sh`):** Session counter and maintenance alerts on session 1 and every 15 sessions.
+* **Standardized Workflows (`.agent/workflows/`):**
+  * `wiki-ingest.md`: 8-step protocol decomposing raw source documents into 5–25 atomic wiki pages.
+  * `wiki-lint.md`: 10-step protocol validating paths, recomputing `mentioned_in`, removing orphans, resolving contradictions, identifying gaps, suggesting source candidates, and rebuilding indexes.
 
 ---
 
@@ -346,7 +337,7 @@ repo-nexus/
 │   ├── workflows/ci.yml            # GitHub Actions CI workflow
 │   └── ISSUE_TEMPLATE/             # Bug report and feature request templates
 ├── tests/
-│   └── test_cli.sh                 # Automated CLI test suite (11 tests)
+│   └── test_cli.sh                 # Automated CLI test suite (21 tests)
 ├── toolkit/                        # Shared prompts, scripts, templates
 ├── package.json                    # npm package manifest
 ├── LICENSE                         # MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-nexus",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "description": "Lightweight, zero-dependency companion tool for multi-repo workspaces and shared AI context via symlinks (no git submodules)",
   "bin": {
     "repo-nexus": "rnex",

package/rnex

@@ -595,6 +595,7 @@ sync_plugins() {
       if [ -f "$_src_path" ] && [ ! -f "$_dest_path" ]; then
         mkdir -p "$(dirname "$_dest_path")"
         cp "$_src_path" "$_dest_path"
+        [ -x "$_src_path" ] && chmod +x "$_dest_path" 2>/dev/null || true
         log_ok "Initialized template: $_d"
       fi
     done
@@ -1096,10 +1097,20 @@ cmd_plugin_enable() {
     if [ -f "$_src_path" ] && [ ! -f "$_dest_path" ]; then
       mkdir -p "$(dirname "$_dest_path")"
       cp "$_src_path" "$_dest_path"
+      [ -x "$_src_path" ] && chmod +x "$_dest_path" 2>/dev/null || true
       log_ok "Initialized template: $_d"
     fi
   done
 
+  # Ensure machine-local state files (like wiki/.lint_trigger_counter) are gitignored
+  _gi="$NEXUS_DIR/.gitignore"
+  if [ -f "$NEXUS_DIR/scripts/wiki-lint-trigger.sh" ]; then
+    if [ ! -f "$_gi" ] || ! grep -qF "wiki/.lint_trigger_counter" "$_gi" 2>/dev/null; then
+      printf '\n# Karpathy LLM Wiki session counter\nwiki/.lint_trigger_counter\n.lint_trigger_counter\n' >> "$_gi"
+      log_dim "Added 'wiki/.lint_trigger_counter' to .gitignore"
+    fi
+  fi
+
   cmd_sync
   log_ok "Plugin '$_name' active across all member repositories"
 }

package/toolkit/plugins/karpathy-llm/README.md

@@ -1,47 +1,152 @@
 # Karpathy LLM Plugin for Repo Nexus
 
-The **`karpathy-llm`** plugin packages Andrej Karpathy's widely adopted agent behavioral rules, context engineering standards, and the LLM Wiki pattern for multi-repository development.
+The **`karpathy-llm`** plugin packages Andrej Karpathy's agent behavioral principles, multi-repo context engineering standards, and the autonomous **Karpathy LLM Wiki** knowledge architecture for AI coding assistants (Cursor, Claude Code, GitHub Copilot, Antigravity, Windsurf).
+
+No external vector databases, embedding pipelines, or MCP servers required — just interlinked markdown files with structured YAML frontmatter traversed natively by AI agents.
+
+Reference specification: [setup-karpathy-wiki.md](https://github.com/nu-nenoi/ai-toolkit/blob/main/prompts/setup-karpathy-wiki.md) (also available locally in [`toolkit/prompts/setup-karpathy-wiki.md`](../../prompts/setup-karpathy-wiki.md)).
 
 ---
 
 ## What It Provides
 
-1. **The 4 Cardinal Principles for Coding Agents (`rules/KARPATHY_RULES.md`):**
-   * **Think Before Coding:** Explicit assumptions, problem formulation, and trade-off evaluation.
-   * **Simplicity First:** Minimal abstractions, readable implementations, and zero boilerplate.
-   * **Surgical Changes:** Minimal blast radius, preserved comments/docstrings, and focused diffs.
-   * **Goal-Driven Execution:** Upfront verification criteria, automated tests, and diff inspection.
+### 1. The 4 Cardinal Principles for Coding Agents (`rules/KARPATHY_RULES.md`)
+* **Think Before Coding:** Explicit assumptions, problem formulation, and trade-off evaluation before writing code.
+* **Simplicity First:** Minimal abstractions, readable implementations, and zero boilerplate bloat.
+* **Surgical Changes:** Minimal blast radius, preserved comments/docstrings, and tightly focused diffs.
+* **Goal-Driven Execution:** Upfront verification criteria, automated tests, and rigorous diff review.
+
+### 2. Multi-Repo Context Engineering & Autonomy
+* Guidelines tailored for Repo Nexus workspaces respecting member repository autonomy and symlink write-through semantics.
+
+### 3. Complete Karpathy LLM Wiki Architecture
+* **`/raw/` Intake Directory:** Append-only directory where unmodified source material (articles, transcripts, docs, meeting notes) is deposited. Includes `.gitkeep`.
+* **`/wiki/` Curated Knowledge Base:** Interlinked atomic markdown pages, each with typed frontmatter relations (`sources`, `related`, `extends`, `contradicts`, `mentioned_in`).
+* **`/wiki/index.md` Control & Navigation Index:** Master categorized catalog containing `lint_trigger: enabled|disabled` to control autonomous maintenance.
+* **`/wiki/hot.md` Rolling Context Cache:** High-density ~500-word orientation summary for rapid agent onboarding without full wiki scans (especially for codebase knowledge and second-brain wikis).
+* **`/wiki/_log.md` Audit Trail:** Append-only log recording every ingest and lint operation with timestamped details.
+* **`/wiki/.lint_trigger_counter` Session Counter:** Machine-local state tracking session activity (ignored in `.gitignore`).
+
+### 4. Autonomous Lint Trigger Script (`scripts/wiki-lint-trigger.sh`)
+* Lightweight POSIX script checking `lint_trigger: enabled` and incrementing `wiki/.lint_trigger_counter`.
+* Alerts agents with `[WIKI MAINTENANCE DUE]: Pending /raw/ files or wiki health checks detected. Run wiki-lint.` on session 1 and every 15 sessions.
+
+### 5. Standardized Agent Workflows (`workflows/`)
+* **`wiki-ingest.md` (8 Steps):** Decomposes raw source documents into 5–25 atomic wiki pages with frontmatter relations.
+* **`wiki-lint.md` (10 Steps):** Integrity audit protocol to validate paths, recompute `mentioned_in`, eliminate orphans, merge duplicates, audit inconsistencies, identify gaps, suggest source candidates, and rebuild indexes.
+
+---
+
+## Step 0 — Configuration Interview
+
+When an AI agent or developer sets up the Karpathy LLM Wiki in a repository or workspace, consult the Step 0 configuration questions:
+
+1. **[Q1] Which AI agent instruction file should the wiki rules be written to?**
+   - `AGENTS.md` (universal, works across most harnesses)
+   - `CLAUDE.md` (Claude Code / Anthropic)
+   - `.cursor/rules/wiki.mdc` (Cursor)
+   - `.github/copilot-instructions.md` (GitHub Copilot)
+   - `GEMINI.md` (Google Gemini / Antigravity)
+   - `.windsurfrules` (Windsurf)
+   - Other — specify path
+
+   *Append the `## Karpathy Wiki Rules` section to that file while preserving all existing content.*
 
-2. **Multi-Repo Context Engineering:**
-   * Clear guidelines for AI agents (Cursor, Claude Code, GitHub Copilot, Antigravity) respecting member repository autonomy and symlink write-through semantics.
+2. **[Q2] What is this wiki for?**
+   - Research / reading list — articles, papers, PDFs on a topic
+   - Personal second brain — meetings, notes, business context, personal projects
+   - Content archive — transcripts, podcast notes, newsletters
+   - Codebase knowledge — architecture decisions, runbooks, team conventions
+   - Other (describe briefly)
 
-3. **LLM Wiki Pattern Scaffolding (`templates/LLM_WIKI.sample.md`):**
-   * A persistent, indexed knowledge base template documenting cross-repo boundaries, contracts, and ADRs so context compounds across developer sessions.
+3. **[Q3] How should the wiki be organized?**
+   - **Flat** — all pages at the top level of `/wiki/` (simpler, good default)
+   - **Structured** — subfolders by category, chosen based on Q2:
+     - Research → `concepts/`, `people/`, `organizations/`, `sources/`, `analysis/`
+     - Second brain → `projects/`, `people/`, `decisions/`, `logs/`
+     - Content archive → `sources/`, `people/`, `tools/`, `concepts/`
+     - Codebase → `architecture/`, `decisions/`, `runbooks/`, `people/`
+   - **Agent decides** — infer structure from the first batch of ingested content
+
+4. **[Q4] Enable wiki automation now?**
+   - **Yes** — set `lint_trigger: enabled` in `/wiki/index.md` frontmatter
+   - **No** — set `lint_trigger: disabled` (can be changed anytime)
+
+---
+
+## Directory Layout Scaffolding
+
+When enabled, the plugin scaffolds:
+
+```text
+my-workspace/
+├── raw/
+│   └── .gitkeep                     # Intake for unmodified source documents
+├── wiki/
+│   ├── index.md                     # Master catalog + lint_trigger toggle
+│   ├── hot.md                       # Rolling ~500-word quick-orient context
+│   ├── _log.md                      # Ingestion & lint audit history
+│   └── .lint_trigger_counter        # Session counter (gitignored)
+├── scripts/
+│   └── wiki-lint-trigger.sh         # Executable session counter & lint alert
+├── .agents/rules/
+│   └── KARPATHY_RULES.md            # Cardinal principles & wiki rules (auto-symlinked)
+├── .agent/workflows/
+│   ├── wiki-ingest.md               # 8-step decomposition & ingestion workflow
+│   └── wiki-lint.md                 # 10-step graph validation & maintenance workflow
+└── docs/
+    ├── wiki-page.template.md        # Atomic page template with typed relations
+    └── LLM_WIKI.sample.md           # Sample wiki walkthrough
+```
 
 ---
 
 ## Enabling in Repo Nexus
 
 ### Option 1: Via CLI (Recommended)
+
 ```bash
 rnex plugin enable karpathy-llm
 ```
 
+This command:
+1. Adds `karpathy-llm` to `plugins:` in `rnex.yaml`.
+2. Copies initial templates (`wiki/index.md`, `wiki/_log.md`, `wiki/hot.md`, `raw/.gitkeep`, `docs/wiki-page.template.md`, `docs/LLM_WIKI.sample.md`, `scripts/wiki-lint-trigger.sh`).
+3. Links `KARPATHY_RULES.md` and workflows into workspace root (`.agents/rules/`, `.agent/workflows/`).
+4. Ensures `wiki/.lint_trigger_counter` is added to `.gitignore`.
+5. Syncs scope links and AI context files across all registered member repositories via `rnex sync`.
+
 ### Option 2: Declarative in `rnex.yaml`
-Add `karpathy-llm` to the `plugins:` list:
+
+Add `karpathy-llm` to `plugins:` in `rnex.yaml`:
+
 ```yaml
 plugins:
   - karpathy-llm
 ```
-Then run:
+
+Then synchronize:
+
 ```bash
 rnex sync
 ```
 
 ---
 
+## Everyday Operation & Cadence
+
+1. **Intake:** Drop raw research papers, meeting notes, PRDs, or architecture specs into `/raw/` unmodified.
+2. **Ingest:** Instruct your AI assistant: *"Run wiki-ingest on raw/source-document.md"*.
+3. **Session Cadence:** After sessions where repository files were edited, run `scripts/wiki-lint-trigger.sh`.
+4. **Maintenance:** If prompted by `[WIKI MAINTENANCE DUE]`, instruct the assistant: *"Run wiki-lint"*.
+5. **Toggle Automation:** Edit `lint_trigger: enabled` or `lint_trigger: disabled` in `/wiki/index.md` anytime.
+
+---
+
 ## Disabling
+
 ```bash
 rnex plugin disable karpathy-llm
 ```
-This safely removes the plugin from `rnex.yaml` and cleans up symlinks from member repositories.
+
+Safely unlinks plugin assets from member repositories and removes the entry from `rnex.yaml`. Your curated `/wiki/` and `/raw/` data remain completely untouched on disk.

package/toolkit/plugins/karpathy-llm/plugin.yaml

@@ -1,9 +1,17 @@
 name: karpathy-llm
-version: 0.1.0
-description: Andrej Karpathy's agent behavioral principles, context engineering guidelines, and LLM Wiki pattern
+version: 0.3.0
+description: Andrej Karpathy's agent behavioral principles, context engineering guidelines, and autonomous LLM Wiki knowledge architecture
 author: nu-nenoi
 homepage: https://github.com/nu-nenoi/repo-nexus
 ai_files:
   - rules/KARPATHY_RULES.md: .agents/rules/KARPATHY_RULES.md
+  - workflows/wiki-ingest.md: .agent/workflows/wiki-ingest.md
+  - workflows/wiki-lint.md: .agent/workflows/wiki-lint.md
 templates:
+  - templates/index.md: wiki/index.md
+  - templates/_log.md: wiki/_log.md
+  - templates/hot.md: wiki/hot.md
+  - templates/raw.gitkeep: raw/.gitkeep
+  - templates/wiki-page.sample.md: docs/wiki-page.template.md
   - templates/LLM_WIKI.sample.md: docs/LLM_WIKI.sample.md
+  - scripts/wiki-lint-trigger.sh: scripts/wiki-lint-trigger.sh

package/toolkit/plugins/karpathy-llm/rules/KARPATHY_RULES.md

@@ -2,7 +2,7 @@
 
 > "The delicate art and science of context engineering: filling the context window with just the right information for the next step." — Andrej Karpathy
 
-These guidelines provide standing operational instructions for AI coding assistants (Cursor, Claude Code, GitHub Copilot, Antigravity, Windsurf) working within multi-repository environments.
+These guidelines provide standing operational instructions for AI coding assistants (Cursor, Claude Code, GitHub Copilot, Antigravity, Windsurf) working within multi-repository environments and managing Karpathy LLM Wiki knowledge bases.
 
 ---
 
@@ -48,10 +48,37 @@ In a Repo Nexus workspace, independent repositories are unified into a single ac
 
 ---
 
-## 3. The LLM Wiki Knowledge Pattern
+## 3. Karpathy Wiki Rules
 
-To prevent architectural knowledge and multi-repo relationships from evaporating between conversation sessions:
+When working in a repository with an active Karpathy LLM Wiki (`/wiki/` and `/raw/` directories):
 
-* **Compile Knowledge into Markdown:** Document cross-repo dependencies, API contracts, and service boundaries in workspace documentation (see `docs/LLM_WIKI.sample.md`).
-* **Treat the Wiki as Living Context:** When an architectural decision or schema change is made, update the corresponding markdown note in the workspace.
-* **Query the Wiki First:** Before embarking on complex multi-repository refactors, inspect the workspace notes to understand existing contracts and constraints.
+- **Intake**: All source material (articles, transcripts, docs, notes) goes to `/raw/` unmodified. Never write directly to `/wiki/` without ingesting.
+- **Orientation**: Before answering domain questions, read `/wiki/index.md` to find relevant pages, then read only those pages. If `hot.md` exists, read it first as a quick-orient step.
+- **Ingestion**: When files appear in `/raw/`, run the `wiki-ingest` workflow (`.agent/workflows/wiki-ingest.md`). One source document typically produces many atomic pages (commonly 5–25 pages) — do not collapse a source into a single file.
+- **Cadence**: After any session where repository files were created, edited, or deleted, run `scripts/wiki-lint-trigger.sh`. If it outputs `[WIKI MAINTENANCE DUE]`, run the `wiki-lint` workflow (`.agent/workflows/wiki-lint.md`) before stopping.
+- **No-op sessions**: Do not run the trigger after read-only or purely conversational sessions where no files changed.
+- **Enable/disable**: Wiki automation is controlled by `lint_trigger: enabled|disabled` in `/wiki/index.md` frontmatter. Edit that field to toggle — the change is committed and visible to the whole team.
+
+---
+
+## 4. Typed Frontmatter Relation Schema
+
+Every page in `/wiki/` must maintain typed frontmatter relations:
+
+```yaml
+---
+title: ""
+tags: []
+last_updated: YYYY-MM-DD
+# Typed relation fields — paths relative to /wiki/
+sources: []          # /raw/ files this page was derived from
+related: []          # thematically related wiki pages
+extends: []          # pages this one builds upon or specialises
+contradicts: []      # pages with conflicting information
+mentioned_in: []     # pages that link to this one (maintained by lint)
+---
+```
+
+**Body:** concise summary, key facts or insights, and inline standard Markdown links (`[Label](./path.md)`) where contextually useful in prose.
+
+The relation graph lives in frontmatter, not in prose links. Agents traverse the graph by reading frontmatter fields, not by scanning body text.

package/toolkit/plugins/karpathy-llm/scripts/wiki-lint-trigger.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+# ============================================================================
+# scripts/wiki-lint-trigger.sh — Autonomous Karpathy Wiki Lint Trigger
+# ============================================================================
+# Check if wiki/index.md exists and contains lint_trigger: enabled.
+# If not, exit silently with code 0.
+grep -q "lint_trigger: enabled" wiki/index.md 2>/dev/null || exit 0
+
+WIKI_DIR="wiki"
+COUNTER_FILE="$WIKI_DIR/.lint_trigger_counter"
+
+# Read and increment session counter
+count=0
+if [ -f "$COUNTER_FILE" ]; then
+  count=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+fi
+case "$count" in
+  ''|*[!0-9]*) count=0 ;;
+esac
+
+count=$((count + 1))
+printf '%s\n' "$count" > "$COUNTER_FILE" 2>/dev/null || true
+
+# If counter is 1 or a multiple of 15, print maintenance due notice
+if [ "$count" -eq 1 ] || [ $((count % 15)) -eq 0 ]; then
+  printf '[WIKI MAINTENANCE DUE]: Pending /raw/ files or wiki health checks detected. Run wiki-lint.\n'
+fi
+
+exit 0

package/toolkit/plugins/karpathy-llm/templates/_log.md

@@ -0,0 +1,9 @@
+# Karpathy Wiki Operation Log
+
+Append-only audit trail recording all ingest (`wiki-ingest`) and maintenance (`wiki-lint`) runs.
+
+---
+
+### Initial Setup — YYYY-MM-DD
+* **Action:** Initialized Karpathy LLM Wiki architecture via `karpathy-llm` plugin.
+* **Control State:** `lint_trigger: enabled`. Intake directory `/raw/` created.

package/toolkit/plugins/karpathy-llm/templates/hot.md

@@ -0,0 +1,11 @@
+# Hot Context (Rolling ~500-Word Cache)
+
+> A compact overview of the most active and immediately relevant domain context. Agents read this file first for quick orientation without needing to parse the full wiki.
+
+## Active Focus & System State
+* **Current State:** Karpathy LLM Wiki initialized.
+* **Recent Ingests:** None yet. Place raw sources into `/raw/` and trigger `wiki-ingest`.
+* **Key Directives:**
+  1. Maintain atomic pages with typed frontmatter relations.
+  2. Update `/wiki/index.md` and this hot cache upon new ingests.
+  3. Run `scripts/wiki-lint-trigger.sh` after sessions modifying project files.

package/toolkit/plugins/karpathy-llm/templates/index.md

@@ -0,0 +1,28 @@
+---
+title: Wiki Index
+last_updated: YYYY-MM-DD
+lint_trigger: enabled   # set to "disabled" to pause all wiki automation
+---
+
+# Wiki Index
+
+Master navigation index and control file for the Karpathy LLM Wiki. Use this index to navigate atomic domain pages, architecture decisions, and cross-project knowledge.
+
+## Overview & Status
+* **Rolling Cache:** [`hot.md`](./hot.md) — Fast ~500-word orientation cache (for second brain or codebase wikis).
+* **Operation Log:** [`_log.md`](./_log.md) — Timestamped ingest & maintenance history.
+
+## Architecture & Concepts
+* *(Atomic concept and system architecture pages will be indexed here during ingestion)*
+
+## Decisions & ADRs
+* *(Architecture decision records, interface contracts, and technical trade-offs)*
+
+## Runbooks & Operations
+* *(Operational procedures, workflows, and team conventions)*
+
+## People & Organizations
+* *(Key contributors, teams, organizations, and stakeholders)*
+
+## Sources & Raw References
+* *(Catalog of ingested source materials from `/raw/`)*

package/toolkit/plugins/karpathy-llm/templates/raw.gitkeep

@@ -0,0 +1 @@
+# Raw intake folder for Karpathy LLM Wiki. Source documents are deposited here unmodified.

package/toolkit/plugins/karpathy-llm/templates/wiki-page.sample.md

@@ -0,0 +1,24 @@
+---
+title: "Concept or Entity Name"
+tags: []
+last_updated: YYYY-MM-DD
+# Typed relation fields — paths relative to /wiki/
+sources: []          # /raw/ files this page was derived from
+related: []          # thematically related wiki pages
+extends: []          # pages this one builds upon or specialises
+contradicts: []      # pages with conflicting information
+mentioned_in: []     # pages that link to this one (maintained by lint)
+---
+
+# Concept or Entity Name
+
+## Summary
+A concise, 1-2 paragraph summary of the concept, entity, architecture decision, or contract.
+
+## Key Facts & Insights
+* **Core Insight:** Grounded directly in source material from `/raw/`.
+* **Scope & Boundaries:** Context of applicability and interfaces with other components.
+
+## Contextual Links
+* Reference [Related Concept](./another-concept.md) where contextually useful in prose.
+*(Note: The relation graph lives in frontmatter, not in prose links. Agents traverse the graph by reading frontmatter fields, not by scanning body text.)*

package/toolkit/plugins/karpathy-llm/workflows/wiki-ingest.md

@@ -0,0 +1,60 @@
+# Wiki Ingestion Workflow (`wiki-ingest`)
+
+Universal workflow for decomposing and ingesting raw source materials into atomic Karpathy LLM Wiki pages.
+
+---
+
+## Ingestion Protocol
+
+1. **Scan Intake:**
+   - Scan `/raw/` for source materials (articles, transcripts, documents, research notes, meeting logs) not yet recorded in `/wiki/_log.md`.
+   - All source material must reside in `/raw/` unmodified. Never write directly to `/wiki/` without ingesting.
+
+2. **Read & Clarify:**
+   - Read each source fully.
+   - If scope, domain boundaries, target audience, or level of detail is unclear, ask one round of clarifying questions before proceeding.
+
+3. **Atomic Decomposition:**
+   - Decompose each source into atomic wiki pages — **one per distinct concept, person, organization, event, or theme** (or architecture decision/contract).
+   - A single source document commonly produces **5–25 pages**. Never collapse an entire source into a single file.
+   - Place pages according to workspace wiki organization:
+     - **Flat:** directly under `/wiki/` (e.g., `/wiki/<topic>.md`)
+     - **Structured:** in categorical subfolders:
+       - Research → `concepts/`, `people/`, `organizations/`, `sources/`, `analysis/`
+       - Second brain → `projects/`, `people/`, `decisions/`, `logs/`
+       - Content archive → `sources/`, `people/`, `tools/`, `concepts/`
+       - Codebase → `architecture/`, `decisions/`, `runbooks/`, `people/`
+
+4. **Frontmatter Relations:**
+   - For each page, write the required YAML frontmatter with typed relations:
+   ```yaml
+   ---
+   title: ""
+   tags: []
+   last_updated: YYYY-MM-DD
+   # Typed relation fields — paths relative to /wiki/
+   sources: []          # /raw/ files this page was derived from
+   related: []          # thematically related wiki pages
+   extends: []          # pages this one builds upon or specialises
+   contradicts: []      # pages with conflicting information
+   mentioned_in: []     # pages that link to this one (leave empty; maintained by lint)
+   ---
+   ```
+   - **Crucial:** The relation graph lives in frontmatter, not in prose links. Agents traverse the graph by reading frontmatter fields, not by scanning body text.
+
+5. **Author Concise Body:**
+   - Write a concise body with summary, key facts, and insights.
+   - Add inline standard Markdown links (`[Label](./path.md)`) where contextually useful in prose.
+
+6. **Update Navigation Index:**
+   - Update `/wiki/index.md` with links to all new pages in their corresponding categorized sections.
+
+7. **Update Hot Cache:**
+   - Update `/wiki/hot.md` if it exists with the rolling ~500-word orientation summary of active context.
+
+8. **Append Operation Log:**
+   - Append a timestamped entry to `/wiki/_log.md` detailing:
+     - Date & time
+     - Raw file processed
+     - List of atomic pages generated
+     - Any flagged follow-ups or knowledge gaps

package/toolkit/plugins/karpathy-llm/workflows/wiki-lint.md

@@ -0,0 +1,47 @@
+# Wiki Lint & Maintenance Workflow (`wiki-lint`)
+
+Periodic health check and maintenance workflow to preserve wiki graph integrity, validate typed relations, recompute bidirectional links, resolve knowledge gaps, and rebuild indexes.
+
+---
+
+## Lint & Maintenance Protocol
+
+1. **Verify Relation Paths:**
+   - For every page, verify that all paths in frontmatter relation fields (`related`, `extends`, `contradicts`, `sources`) resolve to existing files.
+   - Fix or flag broken paths.
+
+2. **Recompute `mentioned_in`:**
+   - Recompute `mentioned_in` for every page by scanning all other pages' relation fields and inline links.
+   - Update the field in frontmatter.
+
+3. **Find Orphaned Pages:**
+   - Detect pages not reachable from `index.md` or any `mentioned_in` field.
+   - Add them to the index in their appropriate category.
+
+4. **Detect Duplicate or Overlapping Pages:**
+   - Detect duplicate or heavily overlapping pages.
+   - Consolidate and update relations across the wiki graph.
+
+5. **Check Factual Inconsistencies:**
+   - Check for factual inconsistencies between pages in `contradicts` relations or covering the same topic.
+   - Clarify or resolve contradictions.
+
+6. **Identify Knowledge Gaps:**
+   - Identify knowledge gaps: concepts referenced in relation fields or prose but lacking their own atomic page.
+   - Create stub pages or flag for future ingest.
+
+7. **Suggest Source Candidates:**
+   - Suggest source candidates from `/raw/` or external searches to fill identified knowledge gaps.
+
+8. **Rebuild Navigation Index:**
+   - Rebuild `/wiki/index.md` to reflect the current set of pages and categories accurately.
+
+9. **Update Hot Cache:**
+   - Update `/wiki/hot.md` if it exists, refreshing the rolling ~500-word orientation context.
+
+10. **Append Operation Log:**
+    - Append a lint summary to `/wiki/_log.md` detailing:
+      - Broken links fixed or flagged
+      - `mentioned_in` updates
+      - Orphans and duplicates resolved
+      - Gaps identified or stubbed

package/toolkit/prompts/setup-karpathy-wiki.md

@@ -0,0 +1,178 @@
+# Karpathy LLM Wiki Scaffolding Prompt
+
+Universal meta-prompt for setting up a Karpathy LLM Wiki knowledge architecture. Works with any AI agent harness. No external MCP servers, vector databases, or embedding pipelines required — just markdown files with structured frontmatter.
+
+---
+
+```markdown
+Set up a Karpathy LLM Wiki in this repository: a self-maintaining knowledge base where raw source material is ingested into interlinked atomic markdown files that any AI agent can navigate by reading indexes and following typed frontmatter relations.
+
+Do not use external MCP servers, vector databases, or embedding pipelines.
+Do not hard-code any specific AI tool or harness into the wiki structure itself.
+
+---
+
+### Step 0 — Configuration (ask before creating any files)
+
+Ask ALL of the following questions and wait for answers:
+
+[Q1] Which AI agent instruction file should the wiki rules be written to?
+  - `AGENTS.md` (universal, works across most harnesses)
+  - `CLAUDE.md` (Claude Code / Anthropic)
+  - `.cursor/rules/wiki.mdc` (Cursor)
+  - `.github/copilot-instructions.md` (GitHub Copilot)
+  - `GEMINI.md` (Google Gemini / Antigravity)
+  - `.windsurfrules` (Windsurf)
+  - Other — specify path
+
+  Append a `## Karpathy Wiki Rules` section to that file. Preserve all existing content.
+
+[Q2] What is this wiki for?
+  - Research / reading list — articles, papers, PDFs on a topic
+  - Personal second brain — meetings, notes, business context, personal projects
+  - Content archive — transcripts, podcast notes, newsletters
+  - Codebase knowledge — architecture decisions, runbooks, team conventions
+  - Other (describe briefly)
+
+[Q3] How should the wiki be organized?
+  - Flat — all pages at the top level of `/wiki/` (simpler, good default)
+  - Structured — subfolders by category, chosen based on Q2 answer
+  - Agent decides — infer structure from the first batch of ingested content
+
+[Q4] Enable wiki automation now?
+  - Yes — set `lint_trigger: enabled` in `/wiki/index.md` frontmatter
+  - No — set `lint_trigger: disabled` (can be changed at any time by editing that field)
+
+---
+
+### 1. Directories and Files
+
+**`/raw/`** — Append-only intake directory. All original source material goes here unmodified. Add `.gitkeep`.
+
+**`/wiki/`** — Curated knowledge base of atomic markdown pages. Structure per Q3:
+  - Flat: all pages directly in `/wiki/`
+  - Structured: subfolders matching the project type from Q2:
+    - Research → `concepts/`, `people/`, `organizations/`, `sources/`, `analysis/`
+    - Second brain → `projects/`, `people/`, `decisions/`, `logs/`
+    - Content archive → `sources/`, `people/`, `tools/`, `concepts/`
+    - Codebase → `architecture/`, `decisions/`, `runbooks/`, `people/`
+
+**`/wiki/index.md`** — Master navigation index and wiki control file. Contains:
+  - YAML frontmatter with `lint_trigger: enabled|disabled` — controls whether the autonomous trigger runs. Committed to version control; toggling is a team-visible decision.
+  - Categorized links to every wiki page. Auto-maintained after every ingest and lint run.
+
+**`/wiki/_log.md`** — Append-only operation log. Every ingest and lint run appends a timestamped entry.
+
+**`/wiki/hot.md`** *(create only for second brain or codebase wiki)* — Rolling ~500-word cache of the most recently relevant context. Lets an agent orient without reading the full wiki.
+
+**`/wiki/.lint_trigger_counter`** — Session counter used by the lint trigger script. Machine-local state. Add to `.gitignore`.
+
+---
+
+### 2. Index File Format
+
+`/wiki/index.md` uses its own frontmatter schema (it is the wiki control file, not a regular page):
+
+```yaml
+---
+title: Wiki Index
+last_updated: YYYY-MM-DD
+lint_trigger: enabled   # set to "disabled" to pause all wiki automation
+---
+```
+
+Followed by categorized Markdown link sections matching the project type from Q2.
+
+---
+
+### 3. Wiki Page Format
+
+Every wiki page is a single atomic markdown file covering one concept, entity, source, or decision.
+
+**Required YAML frontmatter:**
+
+```yaml
+---
+title: ""
+tags: []
+last_updated: YYYY-MM-DD
+# Typed relation fields — paths relative to /wiki/
+sources: []          # /raw/ files this page was derived from
+related: []          # thematically related wiki pages
+extends: []          # pages this one builds upon or specialises
+contradicts: []      # pages with conflicting information
+mentioned_in: []     # pages that link to this one (maintained by lint)
+---
+```
+
+**Body:** concise summary, key facts or insights, and inline standard Markdown links (`[Label](./path.md)`) where contextually useful in prose.
+
+The relation graph lives in frontmatter, not in prose links. Agents traverse the graph by reading frontmatter fields, not by scanning body text.
+
+---
+
+### 4. Agent Instructions
+
+In the file chosen in Q1, append:
+
+```markdown
+## Karpathy Wiki Rules
+
+- **Intake**: All source material (articles, transcripts, docs, notes) goes to `/raw/` unmodified. Never write directly to `/wiki/` without ingesting.
+- **Orientation**: Before answering domain questions, read `/wiki/index.md` to find relevant pages, then read only those pages. If `hot.md` exists, read it first as a quick-orient step.
+- **Ingestion**: When files appear in `/raw/`, run the `wiki-ingest` workflow. One source document typically produces many atomic pages — do not collapse a source into a single file.
+- **Cadence**: After any session where repository files were created, edited, or deleted, run `scripts/wiki-lint-trigger.sh`. If it outputs `[WIKI MAINTENANCE DUE]`, run the `wiki-lint` workflow before stopping.
+- **No-op sessions**: Do not run the trigger after read-only or purely conversational sessions where no files changed.
+- **Enable/disable**: Wiki automation is controlled by `lint_trigger: enabled|disabled` in `/wiki/index.md` frontmatter. Edit that field to toggle — the change is committed and visible to the whole team.
+```
+
+---
+
+### 5. Workflows
+
+Create workflow instruction files at `.agent/workflows/` (or `.agent/skills/` depending on the harness):
+
+**`wiki-ingest.md`**:
+1. Scan `/raw/` for files not yet recorded in `/wiki/_log.md`.
+2. For each source, read it fully. If scope or depth is unclear, ask one round of clarifying questions before proceeding.
+3. Decompose into atomic wiki pages — one per distinct concept, person, organization, event, or theme. A single article commonly produces 5–25 pages.
+4. For each page, write the required frontmatter (including `sources`, `related`, `extends`, `contradicts`). Leave `mentioned_in` empty — lint maintains it.
+5. Write a concise body with inline links where contextually helpful.
+6. Update `/wiki/index.md` with links to all new pages.
+7. Update `/wiki/hot.md` if it exists.
+8. Append a timestamped entry to `/wiki/_log.md`.
+
+**`wiki-lint.md`**:
+1. For every page, verify that all paths in frontmatter relation fields (`related`, `extends`, `contradicts`, `sources`) resolve to existing files. Fix or flag broken paths.
+2. Recompute `mentioned_in` for every page by scanning all other pages' relation fields and inline links. Update the field.
+3. Find orphaned pages (not reachable from `index.md` or any `mentioned_in` field). Add them to the index.
+4. Detect duplicate or heavily overlapping pages. Consolidate and update relations.
+5. Check for factual inconsistencies between pages in `contradicts` relations or covering the same topic.
+6. Identify knowledge gaps: concepts referenced in relation fields but lacking their own page. Create stub pages or flag for future ingest.
+7. Suggest source candidates from `/raw/` or external searches to fill gaps.
+8. Rebuild `/wiki/index.md` to reflect the current set of pages.
+9. Update `/wiki/hot.md` if it exists.
+10. Append a lint summary to `/wiki/_log.md`.
+
+---
+
+### 6. Autonomous Lint Trigger
+
+Create `scripts/wiki-lint-trigger.sh` (POSIX shell):
+- Check if `wiki/index.md` exists and contains `lint_trigger: enabled`. If not, exit silently with code `0`.
+  ```sh
+  grep -q "lint_trigger: enabled" wiki/index.md 2>/dev/null || exit 0
+  ```
+- Read and increment a counter stored in `wiki/.lint_trigger_counter`.
+- If counter is `1` or a multiple of `15`, print:
+  `[WIKI MAINTENANCE DUE]: Pending /raw/ files or wiki health checks detected. Run wiki-lint.`
+- Otherwise exit silently with code `0`.
+- Make executable: `chmod +x scripts/wiki-lint-trigger.sh`.
+
+To disable: set `lint_trigger: disabled` in `/wiki/index.md` frontmatter.
+To re-enable: set `lint_trigger: enabled`.
+
+---
+
+All files must be self-contained with no external dependencies.
+```