repo-nexus 0.4.0 → 0.4.3

package/README.md

@@ -213,7 +213,7 @@ rnex plugin disable karpathy-llm
 
 ### Built-in Plugin: `karpathy-llm`
 The `karpathy-llm` plugin packages Andrej Karpathy's verified LLM agent design patterns, context engineering principles, and the autonomous **Karpathy LLM Wiki** architecture:
-* **The 4 Cardinal Agent Rules** (`.rnex/plugins/karpathy-llm/rules/KARPATHY_RULES.md`):
+* **The 4 Cardinal Agent Rules** (`.rnex/plugins/karpathy-llm/rules/behavioral.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.
@@ -277,7 +277,7 @@ repos:
 |:---|:---|
 | `-c, --config <file>` | Explicit path to `rnex.yaml` (executes in that workspace directory) |
 | `-h, --help` | Display command help and usage instructions |
-| `-v, --version` | Display version (v0.4.0) |
+| `-v, --version` | Display version |
 
 ### Commands
 | Command | Description |
@@ -327,7 +327,7 @@ rnex completion fish | source
 
 ```
 repo-nexus/
-├── package.json                    # npm package manifest (single source of truth for v0.4.0)
+├── package.json                    # npm package manifest (single version source of truth)
 ├── rnex                            # CLI executable (POSIX shell)
 ├── AGENTS.md                       # Routing-only universal AI instructions
 ├── docs/

package/docs/AGENTS.sample.md

@@ -3,14 +3,15 @@
 
 This workspace operates as a **Repo Nexus Virtual Meta-Repo** uniting independent repositories.
 
-## Rules for AI Coding Assistants
+## Routing Protocol for AI Assistants
 
-1. **Read Configuration First (Mandatory)**: AI coding assistants MUST inspect and read `.local.rnex.yaml` (if present) and `rnex.yaml` before planning or executing tasks to understand the workspace structure (`repos_dir`), registered member repositories, and active plugins.
-   - **Highest Priority**: `.local.rnex.yaml` takes highest priority over `rnex.yaml`.
-   - **Default State**: Repositories are enabled by default unless explicitly set to `enabled: false`. Disabled repositories must be excluded from active tasks.
-2. **Repository Boundaries**: Member repositories reside under `repos/<name>/` as independent Git repositories. Edits directly modify files in the respective repository. Do not introduce cross-repo imports unless architected.
-3. **Plugin Instructions & Rules Routing**: Detailed guidelines and workflows for enabled plugins are strictly scoped. AI assistants MUST read instructions for each enabled plugin from its separate directory under:
+AI assistants working in this workspace must route context through the following configuration and instructions files:
+
+1. **Read Configuration First (Highest Priority)**: Inspect and read `.local.rnex.yaml` (if present) and `rnex.yaml` before executing tasks to identify workspace structure (`repos_dir`), active member repositories (`repos/`), and enabled plugins.
+   - `.local.rnex.yaml` takes highest priority over `rnex.yaml`.
+   - Repositories are enabled by default unless explicitly marked `enabled: false`. Disabled repositories are excluded from active tasks.
+2. **Member Repositories (`repos/<name>/`)**: Each member repository is an autonomous Git repository. For repository-specific instructions, inspect `repos/<name>/.rnex/`.
+3. **Plugin Instructions & Rules Routing**: Detailed guidelines and workflows for enabled plugins are located under:
    `.rnex/plugins/<plugin-name>/`
-4. **Member Repo RNEX Context Routing**: AI assistants operating at the workspace level MUST inspect `repos/<name>/.rnex/` for member-specific instructions, guidelines, and commands.
-5. **Git Operations**: Commit and push changes directly within the respective member repository root (`repos/<name>/`).
+4. **Git Operations**: Commit and push changes directly within the respective member repository root (`repos/<name>/`).
 <!-- REPO-NEXUS:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-nexus",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "description": "Lightweight, zero-dependency Virtual Meta-Repo companion for multi-repo workspaces and shared AI context (no git submodules)",
   "bin": {
     "repo-nexus": "rnex",

package/rnex

@@ -85,7 +85,7 @@ resolve_version() {
       fi
     fi
   done
-  printf '0.4.0'
+  printf '0.4.1'
 }
 
 RNEX_VERSION="$(resolve_version)"
@@ -728,6 +728,58 @@ sync_plugins() {
 
 # ---- AI Instructions Management (Routing-Only) ----------------------------
 
+reconcile_gitignore() {
+  _dir="${1:-$NEXUS_DIR}"
+  _gi="$_dir/.gitignore"
+
+  if [ ! -f "$_gi" ]; then
+    cat > "$_gi" <<GI_EOF
+# Member repos (managed by rnex, ignored at workspace level)
+repos/*
+!repos/.gitkeep
+
+# Repo Nexus internal state & cache
+.rnex/
+
+# Local machine-specific configuration
+$RNEX_LOCAL_CONFIG_FILE
+.rnex.local.yaml
+GI_EOF
+    log_ok "Created .gitignore (ignoring repos/, .rnex/, and $RNEX_LOCAL_CONFIG_FILE)"
+    return 0
+  fi
+
+  # 1. Strip any legacy lint_trigger_counter entries if present
+  if grep -q "lint_trigger_counter" "$_gi" 2>/dev/null; then
+    _tmp="$(mktemp)"
+    grep -v "lint_trigger_counter" "$_gi" > "$_tmp" && mv "$_tmp" "$_gi"
+    log_ok "Removed legacy lint trigger counter entries from .gitignore"
+  fi
+
+  # 2. Ensure repos/* is ignored
+  if ! grep -q "^repos" "$_gi" 2>/dev/null; then
+    printf '\n# Member repos (managed by rnex)\nrepos/*\n!repos/.gitkeep\n' >> "$_gi"
+    log_dim "Added repos/* to .gitignore"
+  fi
+
+  # 3. Ensure .rnex/ is ignored
+  if ! grep -q '^\.rnex/' "$_gi" 2>/dev/null && ! grep -q '^\.rnex$' "$_gi" 2>/dev/null; then
+    printf '\n# Repo Nexus internal state & cache\n.rnex/\n' >> "$_gi"
+    log_dim "Added .rnex/ to .gitignore"
+  fi
+
+  # 4. Ensure local config files are ignored
+  if ! grep -qF "$RNEX_LOCAL_CONFIG_FILE" "$_gi" 2>/dev/null; then
+    printf '\n# Local machine-specific configuration\n%s\n' "$RNEX_LOCAL_CONFIG_FILE" >> "$_gi"
+    log_dim "Added $RNEX_LOCAL_CONFIG_FILE to .gitignore"
+  fi
+  if ! grep -qF ".rnex.local.yaml" "$_gi" 2>/dev/null; then
+    printf '.rnex.local.yaml\n' >> "$_gi"
+  fi
+}
+
+# ---- AI Instructions Management (Routing-Only) ----------------------------
+
 AI_MARKER_START="<!-- REPO-NEXUS:START -->"
 AI_MARKER_END="<!-- REPO-NEXUS:END -->"
 
@@ -737,16 +789,17 @@ get_rnex_instructions() {
 
 This workspace operates as a **Repo Nexus Virtual Meta-Repo** uniting independent repositories.
 
-## Rules for AI Coding Assistants
+## Routing Protocol for AI Assistants
+
+AI assistants working in this workspace must route context through the following configuration and instructions files:
 
-1. **Read Configuration First (Mandatory)**: AI coding assistants MUST inspect and read `.local.rnex.yaml` (if present) and `rnex.yaml` before planning or executing tasks to understand the workspace structure (`repos_dir`), registered member repositories, and active plugins.
-   - **Highest Priority**: `.local.rnex.yaml` takes highest priority over `rnex.yaml`.
-   - **Default State**: Repositories are enabled by default unless explicitly set to `enabled: false`. Disabled repositories must be excluded from active tasks.
-2. **Repository Boundaries**: Member repositories reside under `repos/<name>/` as independent Git repositories. Edits directly modify files in the respective repository. Do not introduce cross-repo imports unless architected.
-3. **Plugin Instructions & Rules Routing**: Detailed guidelines and workflows for enabled plugins are strictly scoped. AI assistants MUST read instructions for each enabled plugin from its separate directory under:
+1. **Read Configuration First (Highest Priority)**: Inspect and read `.local.rnex.yaml` (if present) and `rnex.yaml` before executing tasks to identify workspace structure (`repos_dir`), active member repositories (`repos/`), and enabled plugins.
+   - `.local.rnex.yaml` takes highest priority over `rnex.yaml`.
+   - Repositories are enabled by default unless explicitly marked `enabled: false`. Disabled repositories are excluded from active tasks.
+2. **Member Repositories (`repos/<name>/`)**: Each member repository is an autonomous Git repository. For repository-specific instructions, inspect `repos/<name>/.rnex/`.
+3. **Plugin Instructions & Rules Routing**: Detailed guidelines and workflows for enabled plugins are located under:
    `.rnex/plugins/<plugin-name>/`
-4. **Member Repo RNEX Context Routing**: AI assistants operating at the workspace level MUST inspect `repos/<name>/.rnex/` for member-specific instructions, guidelines, and commands.
-5. **Git Operations**: Commit and push changes directly within the respective member repository root (`repos/<name>/`).
+4. **Git Operations**: Commit and push changes directly within the respective member repository root (`repos/<name>/`).
 AGENTS_EOF
 }
 
@@ -757,15 +810,17 @@ merge_rnex_instructions() {
 
   if [ ! -f "$_dst" ]; then
     mkdir -p "$(dirname "$_dst")"
-    printf '%s\n' "$AI_MARKER_START" > "$_dst"
-    cat "$_body_tmp" >> "$_dst"
-    printf '\n%s\n' "$AI_MARKER_END" >> "$_dst"
+    {
+      printf '%s\n' "$AI_MARKER_START"
+      cat "$_body_tmp"
+      printf '\n%s\n' "$AI_MARKER_END"
+    } > "$_dst"
     rm -f "$_body_tmp"
     log_ok "Created $(basename "$_dst") with Repo Nexus routing instructions"
     return 0
   fi
 
-  # If delimiters already exist, update the block in-place
+  # Case 1: If delimiters already exist, update the block in-place
   if grep -qF "$AI_MARKER_START" "$_dst" 2>/dev/null; then
     _tmp="$(mktemp)"
     awk -v s="$AI_MARKER_START" -v e="$AI_MARKER_END" -v src="$_body_tmp" '
@@ -784,18 +839,51 @@ merge_rnex_instructions() {
       !in_b { print }
     ' "$_dst" > "$_tmp" && mv "$_tmp" "$_dst"
     rm -f "$_body_tmp"
-    log_ok "Updated Repo Nexus instructions in $(basename "$_dst")"
+    log_ok "Updated Repo Nexus routing instructions in $(basename "$_dst")"
     return 0
   fi
 
-  # If no delimiters, check if file already has up-to-date rnex instructions
-  if grep -q "rnex.yaml" "$_dst" 2>/dev/null && grep -qi "Plugin Instructions" "$_dst" 2>/dev/null; then
+  # Case 2: If no delimiters, check for legacy un-delimited Repo Nexus block
+  # (e.g. starting with "# Multi-Repo AI Workspace Context" or containing "Symlink Write-Through")
+  if grep -q "Multi-Repo AI Workspace Context" "$_dst" 2>/dev/null || grep -q "Symlink Write-Through" "$_dst" 2>/dev/null; then
+    _tmp="$(mktemp)"
+    awk -v s="$AI_MARKER_START" -v e="$AI_MARKER_END" -v src="$_body_tmp" '
+      BEGIN { in_legacy = 0; replaced = 0 }
+      /^# Multi-Repo AI Workspace Context/ {
+        in_legacy = 1
+        if (!replaced) {
+          print s
+          while ((getline line < src) > 0) print line
+          close(src)
+          print e
+          replaced = 1
+        }
+        next
+      }
+      in_legacy {
+        if (/^# [^#]/ && !/^# Multi-Repo/) {
+          in_legacy = 0
+          print
+          next
+        }
+        next
+      }
+      !in_legacy { print }
+      END {
+        if (!replaced) {
+          print s
+          while ((getline line < src) > 0) print line
+          close(src)
+          print e
+        }
+      }
+    ' "$_dst" > "$_tmp" && mv "$_tmp" "$_dst"
     rm -f "$_body_tmp"
-    log_info "$(basename "$_dst") already contains Repo Nexus instructions"
+    log_ok "Upgraded legacy instructions to Repo Nexus routing block in $(basename "$_dst")"
     return 0
   fi
 
-  # Append rnex instructions block to existing instructions
+  # Case 3: Completely custom instructions file without rnex context — append delimited block
   _tmp="$(mktemp)"
   cp "$_dst" "$_tmp"
   if [ -s "$_tmp" ] && [ -n "$(tail -c 1 "$_tmp" 2>/dev/null)" ]; then
@@ -808,7 +896,7 @@ merge_rnex_instructions() {
   } >> "$_tmp"
   mv "$_tmp" "$_dst"
   rm -f "$_body_tmp"
-  log_ok "Merged Repo Nexus instructions with existing $(basename "$_dst")"
+  log_ok "Merged Repo Nexus routing instructions with existing $(basename "$_dst")"
 }
 
 # ============================================================================
@@ -903,29 +991,8 @@ YAML_EOF
   mkdir -p "$_target_dir/.rnex"
   mkdir -p "$_target_dir/.rnex/plugins"
 
-  # ---- 6. Ensure repos/ and local configs are gitignored -------------------
-  _target_gi="$_target_dir/.gitignore"
-  if [ ! -f "$_target_gi" ]; then
-    cat > "$_target_gi" <<GI_EOF
-# Member repos (managed by rnex, ignored at workspace level)
-repos/*
-!repos/.gitkeep
-
-# Local machine-specific configuration
-$RNEX_LOCAL_CONFIG_FILE
-.rnex.local.yaml
-GI_EOF
-    log_ok "Created .gitignore (ignoring repos/ and $RNEX_LOCAL_CONFIG_FILE)"
-  else
-    if ! grep -q "^repos" "$_target_gi" 2>/dev/null; then
-      printf '\n# Member repos (managed by rnex)\nrepos/*\n!repos/.gitkeep\n' >> "$_target_gi"
-      log_dim "Added repos/* to .gitignore"
-    fi
-    if ! grep -qF "$RNEX_LOCAL_CONFIG_FILE" "$_target_gi" 2>/dev/null; then
-      printf '\n# Local machine-specific configuration\n%s\n.rnex.local.yaml\n' "$RNEX_LOCAL_CONFIG_FILE" >> "$_target_gi"
-      log_dim "Added $RNEX_LOCAL_CONFIG_FILE to .gitignore"
-    fi
-  fi
+  # ---- 6. Ensure repos/, .rnex/, and local configs are gitignored ---------
+  reconcile_gitignore "$_target_dir"
 
   if [ "$_config_created" -eq 1 ]; then
     printf '\n'
@@ -1217,10 +1284,18 @@ cmd_status() {
   printf '  %b●%b Repos Dir:     %s\n' "$_DIM" "$_NC" "$REPOS_DIR"
 
   _gi="$NEXUS_DIR/.gitignore"
-  if [ -f "$_gi" ] && grep -q '^repos' "$_gi" 2>/dev/null && grep -qF "$RNEX_LOCAL_CONFIG_FILE" "$_gi" 2>/dev/null; then
-    printf '  %b✓%b Git Ignore:    repos/ and %s ignored in .gitignore\n' "$_G" "$_NC" "$RNEX_LOCAL_CONFIG_FILE"
+  _gi_repos=0; _gi_rnex=0; _gi_local=0; _gi_has_counter=0
+  if [ -f "$_gi" ]; then
+    grep -q '^repos' "$_gi" 2>/dev/null && _gi_repos=1
+    (grep -q '^\.rnex/' "$_gi" 2>/dev/null || grep -q '^\.rnex$' "$_gi" 2>/dev/null) && _gi_rnex=1
+    grep -qF "$RNEX_LOCAL_CONFIG_FILE" "$_gi" 2>/dev/null && _gi_local=1
+    grep -q "lint_trigger_counter" "$_gi" 2>/dev/null && _gi_has_counter=1
+  fi
+
+  if [ "$_gi_repos" -eq 1 ] && [ "$_gi_rnex" -eq 1 ] && [ "$_gi_local" -eq 1 ] && [ "$_gi_has_counter" -eq 0 ]; then
+    printf '  %b✓%b Git Ignore:    repos/, .rnex/, and %s ignored in .gitignore\n' "$_G" "$_NC" "$RNEX_LOCAL_CONFIG_FILE"
   else
-    printf '  %b!%b Git Ignore:    recommend running "rnex fix" to ignore repos/ and local configs\n' "$_Y" "$_NC"
+    printf '  %b!%b Git Ignore:    recommend running "rnex fix" to update .gitignore (repos/, .rnex/, local configs)\n' "$_Y" "$_NC"
   fi
   printf '\n'
 
@@ -1302,32 +1377,13 @@ cmd_fix() {
 
   log_info "Reconciling Repo Nexus workspace at $NEXUS_DIR..."
 
-  # 1. Ensure .gitignore ignores repos/ and .local.rnex.yaml
-  _gi="$NEXUS_DIR/.gitignore"
-  if [ ! -f "$_gi" ]; then
-    cat > "$_gi" <<GI_EOF
-# Member repos (managed by rnex)
-repos/*
-!repos/.gitkeep
-
-# Local machine-specific configuration
-$RNEX_LOCAL_CONFIG_FILE
-.rnex.local.yaml
-GI_EOF
-    log_ok "Created .gitignore"
-  else
-    if ! grep -q "^repos" "$_gi" 2>/dev/null; then
-      printf '\n# Member repos (managed by rnex)\nrepos/*\n!repos/.gitkeep\n' >> "$_gi"
-      log_ok "Added repos/* to .gitignore"
-    fi
-    if ! grep -qF "$RNEX_LOCAL_CONFIG_FILE" "$_gi" 2>/dev/null; then
-      printf '\n# Local machine-specific configuration\n%s\n.rnex.local.yaml\n' "$RNEX_LOCAL_CONFIG_FILE" >> "$_gi"
-      log_ok "Added $RNEX_LOCAL_CONFIG_FILE to .gitignore"
-    fi
-  fi
+  # 1. Ensure .gitignore ignores repos/, .rnex/, and local configs, and strips legacy counters
+  reconcile_gitignore "$NEXUS_DIR"
 
-  # 2. Reconcile instructions in AGENTS.md
+  # 2. Reconcile instructions in AGENTS.md (and optional AI assistant files if present)
   merge_rnex_instructions "$NEXUS_DIR/AGENTS.md"
+  [ -f "$NEXUS_DIR/CLAUDE.md" ] && merge_rnex_instructions "$NEXUS_DIR/CLAUDE.md"
+  [ -f "$NEXUS_DIR/.cursorrules" ] && merge_rnex_instructions "$NEXUS_DIR/.cursorrules"
 
   # 3. Reconcile plugins
   sync_plugins

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

@@ -10,16 +10,16 @@ Reference specification: [setup-karpathy-wiki.md](https://github.com/nu-nenoi/ai
 
 ## What It Provides
 
-### 1. The 4 Cardinal Principles for Coding Agents (`rules/KARPATHY_RULES.md`)
+### 1. The 4 Cardinal Principles for Coding Agents (`rules/behavioral.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.
+### 2. Multi-Repo Context Engineering & Autonomy (`rules/behavioral.md`)
+* Guidelines tailored for Repo Nexus workspaces respecting member repository autonomy and physical repository boundaries.
 
-### 3. Complete Karpathy LLM Wiki Architecture
+### 3. Complete Karpathy LLM Wiki Architecture (`instructions/wiki-architecture.md`)
 * **`/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` Navigation Index:** Master categorized catalog organizing atomic concepts, architecture decisions, and cross-project knowledge.
@@ -37,7 +37,7 @@ Reference specification: [setup-karpathy-wiki.md](https://github.com/nu-nenoi/ai
 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?**
-   - In a **Repo Nexus workspace**: Instructions are maintained in separate instructions files (`.rnex/instructions/karpathy-llm.md` and `.rnex/rules/KARPATHY_RULES.md`). Agents read `rnex.yaml` to detect enabled plugins and read their dedicated instructions files automatically.
+   - In a **Repo Nexus workspace**: Instructions are scoped under `.rnex/plugins/karpathy-llm/` (`rules/behavioral.md` and `instructions/wiki-architecture.md`). Agents read `rnex.yaml` to detect enabled plugins and route context automatically.
    - In a **standalone setup** (outside Repo Nexus):
      - `AGENTS.md` (universal, works across most harnesses)
      - `CLAUDE.md` (Claude Code / Anthropic)
@@ -79,16 +79,18 @@ my-workspace/
 │   ├── hot.md                       # Rolling ~500-word quick-orient context
 │   └── _log.md                      # Ingestion & lint audit history
 ├── .rnex/
-│   ├── instructions/
-│   │   └── karpathy-llm.md          # Dedicated plugin instructions (auto-symlinked)
-│   ├── rules/
-│   │   └── KARPATHY_RULES.md        # Cardinal principles & wiki rules (auto-symlinked)
-│   ├── workflows/
-│   │   ├── wiki-ingest.md           # 8-step decomposition & ingestion workflow
-│   │   └── wiki-lint.md             # 10-step graph validation & maintenance workflow
-│   └── templates/
-│       ├── wiki-page.template.md    # Atomic page template with typed relations
-│       └── LLM_WIKI.sample.md       # Sample wiki walkthrough
+│   └── plugins/
+│       └── karpathy-llm/
+│           ├── instructions/
+│           │   └── wiki-architecture.md# LLM Wiki architecture & relation schema
+│           ├── rules/
+│           │   └── behavioral.md    # Cardinal principles & context engineering
+│           ├── workflows/
+│           │   ├── wiki-ingest.md   # 8-step decomposition & ingestion workflow
+│           │   └── wiki-lint.md     # 10-step graph validation & maintenance workflow
+│           └── templates/
+│               ├── wiki-page.template.md# Atomic page template with typed relations
+│               └── LLM_WIKI.sample.md# Sample wiki walkthrough
 └── rnex.yaml                        # Plugin configuration
 ```
 
@@ -105,7 +107,7 @@ 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`, `.rnex/templates/wiki-page.template.md`, `.rnex/templates/LLM_WIKI.sample.md`).
-3. Links `KARPATHY_RULES.md` and workflows into `.rnex/rules/` and `.rnex/workflows/`.
+3. Scopes `rules/`, `instructions/`, and `workflows/` into `.rnex/plugins/karpathy-llm/`.
 4. Syncs scope links and AI context files across all registered member repositories via `rnex fix`.
 
 ### Option 2: Declarative in `rnex.yaml`

package/toolkit/plugins/karpathy-llm/instructions/wiki-architecture.md

@@ -0,0 +1,43 @@
+# Karpathy LLM Wiki Knowledge Architecture
+
+> "A persistent, compounding knowledge base optimized for AI agents." — Andrej Karpathy
+
+This instruction document defines the operational rules, intake lifecycle, and typed relation schema for the Karpathy LLM Wiki (`/wiki/` and `/raw/` directories).
+
+---
+
+## 1. Operating Rules
+
+When working in a workspace with an active Karpathy LLM Wiki:
+
+- **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 (`.rnex/plugins/karpathy-llm/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.
+- **Maintenance**: Run the `wiki-lint` workflow (`.rnex/plugins/karpathy-llm/workflows/wiki-lint.md`) to validate paths, update `mentioned_in`, and preserve graph integrity.
+
+---
+
+## 2. 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 Structure:**
+- Concise summary of the concept.
+- Key facts, definitions, or insights.
+- 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/plugin.yaml

@@ -1,14 +1,14 @@
 name: karpathy-llm
-version: 0.4.0
+version: 0.4.1
 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
 rules:
-  - rules/KARPATHY_RULES.md: .rnex/plugins/karpathy-llm/rules/KARPATHY_RULES.md
+  - rules/behavioral.md: .rnex/plugins/karpathy-llm/rules/behavioral.md
   - workflows/wiki-ingest.md: .rnex/plugins/karpathy-llm/workflows/wiki-ingest.md
   - workflows/wiki-lint.md: .rnex/plugins/karpathy-llm/workflows/wiki-lint.md
 instructions:
-  - instructions/karpathy-llm.md: .rnex/plugins/karpathy-llm/instructions/karpathy-llm.md
+  - instructions/wiki-architecture.md: .rnex/plugins/karpathy-llm/instructions/wiki-architecture.md
 templates:
   - templates/index.md: wiki/index.md
   - templates/_log.md: wiki/_log.md

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

@@ -0,0 +1,47 @@
+# Karpathy Coding Agent Behavioral Principles
+
+> "The delicate art and science of context engineering: filling the context window with just the right information for the next step." — Andrej Karpathy
+
+These rules define standing behavioral principles for AI coding assistants (Cursor, Claude Code, GitHub Copilot, Antigravity, Windsurf) working in this workspace.
+
+---
+
+## 1. The Four Cardinal Principles
+
+### Principle 1: Think Before Coding
+* **State Assumptions Explicitly:** Before implementing any non-trivial change, state your understanding of the problem, assumptions made, and proposed solution.
+* **Surface Trade-Offs:** If multiple approaches exist, outline the alternatives with their trade-offs before generating code.
+* **Verify Repository Boundaries:** In multi-repo workspaces, determine which member repositories are affected. Never make silent architectural assumptions that span across repo boundaries.
+
+### Principle 2: Simplicity First
+* **Favor Readable Over Clever:** Write the simplest code that solves the immediate problem. Avoid unnecessary abstractions, speculative generics, and premature optimizations.
+* **Zero Boilerplate Bloat:** Do not introduce extra wrapper layers, helper classes, or framework-heavy patterns unless explicitly requested or required by existing codebase conventions.
+* **Less Code is Better Code:** If an existing utility, POSIX primitive, or library function does the job, reuse it.
+
+### Principle 3: Surgical Changes
+* **Minimal Blast Radius:** Touch *only* the lines and files required to achieve the goal.
+* **Preserve Documentation & Comments:** Never delete or overwrite existing comments, documentation, or code structure unrelated to your changes.
+* **Zero Unintended Reformatting:** Avoid running blanket code formatters across entire files that create massive, unreadable git diffs. Keep diffs tight, focused, and reviewable.
+
+### Principle 4: Goal-Driven Execution & Verification
+* **Define Success Criteria Upfront:** Know how you will prove that your change works before you write the first line of code.
+* **Verify with Automated Checks:** Run linters, unit tests, and build commands before declaring a task complete.
+* **Inspect the Diff:** Review your own git diff before committing or presenting the solution to ensure no extraneous changes were introduced.
+
+---
+
+## 2. Multi-Repo Context Engineering
+
+In a Repo Nexus workspace, independent repositories are organized into `./repos/<name>/` as autonomous Git repositories. Coding agents must follow these rules:
+
+1. **Repository Boundaries:**
+   - Edits made to `repos/<name>/` modify the underlying member repository directly.
+   - Member repositories are autonomous projects. Do not introduce cross-repository source imports or shared runtime dependencies unless an explicit monorepo architecture is configured.
+
+2. **Member .rnex Directory Routing:**
+   - Member repositories may contain an `.rnex/` directory (e.g. `repos/<name>/.rnex/`) containing repository-specific documents, instructions, rules, workflows, and scripts. Coding assistants must inspect this directory for member-specific instructions.
+   - Run git operations (commits, branches, pushes) directly within the respective member repository root (`repos/<name>/`).
+
+3. **Context Economy:**
+   - Do not redundantly read entire files or directory trees when targeted symbol lookups or line ranges suffice.
+   - Rely on active workspace context, indexing, and compiled documentation rather than re-scanning raw files repeatedly.

package/toolkit/plugins/karpathy-llm/templates/LLM_WIKI.sample.md

@@ -8,7 +8,7 @@
 
 * **Workspace Name:** `my-multi-repo-workspace`
 * **Orchestrator:** Repo Nexus (`rnex`)
-* **Primary Scope:** Symlinked repositories under `./repos/`
+* **Primary Scope:** Member repositories under `./repos/`
 
 ---
 
@@ -36,8 +36,8 @@
 
 ### ADR-001: Independent Git Repositories over Monorepo
 * **Date:** YYYY-MM-DD
-* **Decision:** Keep repositories completely independent without Git submodules. Orchestrate via Repo Nexus symlinks.
-* **Consequences:** Autonomous CI/CD per repo; AI assistants maintain shared context via `AGENTS.md` and `KARPATHY_RULES.md`.
+* **Decision:** Keep repositories completely independent without Git submodules. Orchestrate via Repo Nexus Virtual Meta-Repo.
+* **Consequences:** Autonomous CI/CD per repo; AI assistants maintain shared context via `AGENTS.md` and `behavioral.md`.
 
 ---
 

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

@@ -17,7 +17,7 @@ Do not hard-code any specific AI tool or harness into the wiki structure itself.
 Ask ALL of the following questions and wait for answers:
 
 [Q1] Which AI agent instruction file should the wiki rules be written to?
-  - In a Repo Nexus workspace: plugin instructions are maintained in separate instructions files (`.rnex/instructions/karpathy-llm.md` and `.rnex/rules/KARPATHY_RULES.md`). Agents read `rnex.yaml` to detect enabled plugins and read their separate instructions files.
+  - In a Repo Nexus workspace: plugin instructions are maintained under `.rnex/plugins/karpathy-llm/` (`rules/behavioral.md` and `instructions/wiki-architecture.md`). Agents read `rnex.yaml` to detect enabled plugins and read their scoped files.
   - In a standalone setup (outside Repo Nexus):
     - `AGENTS.md` (universal, works across most harnesses)
     - `CLAUDE.md` (Claude Code / Anthropic)

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

@@ -1,83 +0,0 @@
-# Karpathy LLM Agent Guidelines & Behavioral Principles
-
-> "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 and managing Karpathy LLM Wiki knowledge bases.
-
----
-
-## 1. The Four Cardinal Principles
-
-### Principle 1: Think Before Coding
-* **State Assumptions Explicitly:** Before implementing any non-trivial change, state your understanding of the problem, assumptions made, and proposed solution.
-* **Surface Trade-Offs:** If multiple approaches exist, outline the alternatives with their trade-offs before generating code.
-* **Verify Repository Boundaries:** In multi-repo workspaces, determine which member repositories are affected. Never make silent architectural assumptions that span across repo boundaries.
-
-### Principle 2: Simplicity First
-* **Favor Readable Over Clever:** Write the simplest code that solves the immediate problem. Avoid unnecessary abstractions, speculative generics, and premature optimizations.
-* **Zero Boilerplate Bloat:** Do not introduce extra wrapper layers, helper classes, or framework-heavy patterns unless explicitly requested or required by existing codebase conventions.
-* **Less Code is Better Code:** If an existing utility, POSIX primitive, or library function does the job, reuse it.
-
-### Principle 3: Surgical Changes
-* **Minimal Blast Radius:** Touch *only* the lines and files required to achieve the goal.
-* **Preserve Documentation & Comments:** Never delete or overwrite existing comments, documentation, or code structure unrelated to your changes.
-* **Zero Unintended Reformatting:** Avoid running blanket code formatters across entire files that create massive, unreadable git diffs. Keep diffs tight, focused, and reviewable.
-
-### Principle 4: Goal-Driven Execution & Verification
-* **Define Success Criteria Upfront:** Know how you will prove that your change works before you write the first line of code.
-* **Verify with Automated Checks:** Run linters, unit tests, and build commands before declaring a task complete.
-* **Inspect the Diff:** Review your own git diff before committing or presenting the solution to ensure no extraneous changes were introduced.
-
----
-
-## 2. Multi-Repo Context Engineering
-
-In a Repo Nexus workspace, independent repositories are unified into a single active scope via Unix symlinks. Coding agents must follow these rules:
-
-1. **Symlink Write-Through:**
-   - Edits made to `repos/<name>/` write directly through to the underlying member repository on disk.
-   - Do not attempt to move or replace symlinks with regular directories.
-
-2. **Repository Autonomy & Member .rnex Directory:**
-   - Member repositories are independent projects. Do not introduce cross-repository source imports or shared runtime dependencies unless an explicit monorepo architecture is configured.
-   - Member repositories may contain an `.rnex/` directory (e.g. `repos/<name>/.rnex/`) containing repository-specific documents, instructions, rules, workflows, and scripts. Coding assistants must inspect this directory for member-specific instructions.
-   - Run git operations (commits, branches, pushes) within the respective member repository root.
-
-3. **Context Economy:**
-   - Do not redundantly read entire files or directory trees when targeted symbol lookups or line ranges suffice.
-   - Rely on active workspace context, indexing, and compiled documentation rather than re-scanning raw files repeatedly.
-
----
-
-## 3. Karpathy Wiki Rules
-
-When working in a repository with an active Karpathy LLM Wiki (`/wiki/` and `/raw/` directories):
-
-- **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 (`.rnex/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.
-- **Maintenance**: Run the `wiki-lint` workflow (`.rnex/workflows/wiki-lint.md`) to validate paths, update `mentioned_in`, and preserve graph integrity.
-
----
-
-## 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/rules/KARPATHY_RULES.md

@@ -1,83 +0,0 @@
-# Karpathy LLM Agent Guidelines & Behavioral Principles
-
-> "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 and managing Karpathy LLM Wiki knowledge bases.
-
----
-
-## 1. The Four Cardinal Principles
-
-### Principle 1: Think Before Coding
-* **State Assumptions Explicitly:** Before implementing any non-trivial change, state your understanding of the problem, assumptions made, and proposed solution.
-* **Surface Trade-Offs:** If multiple approaches exist, outline the alternatives with their trade-offs before generating code.
-* **Verify Repository Boundaries:** In multi-repo workspaces, determine which member repositories are affected. Never make silent architectural assumptions that span across repo boundaries.
-
-### Principle 2: Simplicity First
-* **Favor Readable Over Clever:** Write the simplest code that solves the immediate problem. Avoid unnecessary abstractions, speculative generics, and premature optimizations.
-* **Zero Boilerplate Bloat:** Do not introduce extra wrapper layers, helper classes, or framework-heavy patterns unless explicitly requested or required by existing codebase conventions.
-* **Less Code is Better Code:** If an existing utility, POSIX primitive, or library function does the job, reuse it.
-
-### Principle 3: Surgical Changes
-* **Minimal Blast Radius:** Touch *only* the lines and files required to achieve the goal.
-* **Preserve Documentation & Comments:** Never delete or overwrite existing comments, documentation, or code structure unrelated to your changes.
-* **Zero Unintended Reformatting:** Avoid running blanket code formatters across entire files that create massive, unreadable git diffs. Keep diffs tight, focused, and reviewable.
-
-### Principle 4: Goal-Driven Execution & Verification
-* **Define Success Criteria Upfront:** Know how you will prove that your change works before you write the first line of code.
-* **Verify with Automated Checks:** Run linters, unit tests, and build commands before declaring a task complete.
-* **Inspect the Diff:** Review your own git diff before committing or presenting the solution to ensure no extraneous changes were introduced.
-
----
-
-## 2. Multi-Repo Context Engineering
-
-In a Repo Nexus workspace, independent repositories are unified into a single active scope via Unix symlinks. Coding agents must follow these rules:
-
-1. **Symlink Write-Through:**
-   - Edits made to `repos/<name>/` write directly through to the underlying member repository on disk.
-   - Do not attempt to move or replace symlinks with regular directories.
-
-2. **Repository Autonomy & Member .rnex Directory:**
-   - Member repositories are independent projects. Do not introduce cross-repository source imports or shared runtime dependencies unless an explicit monorepo architecture is configured.
-   - Member repositories may contain an `.rnex/` directory (e.g. `repos/<name>/.rnex/`) containing repository-specific documents, instructions, rules, workflows, and scripts. Coding assistants must inspect this directory for member-specific instructions.
-   - Run git operations (commits, branches, pushes) within the respective member repository root.
-
-3. **Context Economy:**
-   - Do not redundantly read entire files or directory trees when targeted symbol lookups or line ranges suffice.
-   - Rely on active workspace context, indexing, and compiled documentation rather than re-scanning raw files repeatedly.
-
----
-
-## 3. Karpathy Wiki Rules
-
-When working in a repository with an active Karpathy LLM Wiki (`/wiki/` and `/raw/` directories):
-
-- **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 (`.rnex/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.
-- **Maintenance**: Run the `wiki-lint` workflow (`.rnex/workflows/wiki-lint.md`) to validate paths, update `mentioned_in`, and preserve graph integrity.
-
----
-
-## 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.