repo-nexus 0.8.1 → 0.8.2

package/README.md

@@ -23,12 +23,12 @@ A **Virtual Meta-Repo** companion for multi-repo workspaces and shared AI contex
 >
 > Explore the comprehensive documentation, architecture guides, and interactive references on the **[Documentation Site](https://unoxen.github.io/repo-nexus/)**:
 >
-> - 🚀 **[Getting Started](https://unoxen.github.io/repo-nexus/guide/getting-started)** — Step-by-step onboarding walkthrough and workspace setup
-> - 📐 **[Architecture](https://unoxen.github.io/repo-nexus/guide/architecture)** & **[Why Repo Nexus?](https://unoxen.github.io/repo-nexus/guide/why-repo-nexus)** — Virtual Meta-Repo model, directory layout, and design rationale
-> - 💻 **[CLI Reference](https://unoxen.github.io/repo-nexus/cli/)** — Complete command syntax, global flags, batch execution (`rnex exec`), and Git hooks
-> - 🧩 **[Plugins Guide](https://unoxen.github.io/repo-nexus/plugins/)** — AI provider integrations (Claude, Codex, Copilot, Cursor, Gemini, Windsurf) and Karpathy LLM Wiki
-> - ⚙️ **[Configuration Schema](https://unoxen.github.io/repo-nexus/guide/configuration)** — Two-level `rnex.yaml` and `.local.rnex.yaml` specification
-> - ❓ **[Frequently Asked Questions (FAQ)](https://unoxen.github.io/repo-nexus/faq/)** — Common questions, Git submodule differences, and context strategies
+> - 🚀 **[Getting Started](https://unoxen.github.io/repo-nexus/introduction/quick-start)** — Step-by-step onboarding walkthrough and workspace setup
+> - 📐 **[Architecture](https://unoxen.github.io/repo-nexus/documentation/architecture)** & **[Why Repo Nexus?](https://unoxen.github.io/repo-nexus/introduction/why-rnex)** — Virtual Meta-Repo model, directory layout, and design rationale
+> - 💻 **[CLI Reference](https://unoxen.github.io/repo-nexus/reference/cli)** — Complete command syntax, global flags, batch execution (`rnex exec`), and Git hooks
+> - 🧩 **[Plugins Guide](https://unoxen.github.io/repo-nexus/documentation/plugin-ecosystem)** — AI provider integrations (Claude, Codex, Copilot, Cursor, Gemini, Windsurf) and Karpathy LLM Wiki
+> - ⚙️ **[Configuration Schema](https://unoxen.github.io/repo-nexus/documentation/configuration)** — Two-level `rnex.yaml` and `.local.rnex.yaml` specification
+> - ❓ **[Frequently Asked Questions (FAQ)](https://unoxen.github.io/repo-nexus/faq/general)** — Common questions, Git submodule differences, and context strategies
 
 ---
 
@@ -145,11 +145,11 @@ repo-nexus/
 │   ├── ai-instructions.sample.md   # Base template for .rnex/ai-instructions.md
 │   └── rnex.example.yaml           # Full config reference with examples
 ├── docs/
-│   ├── guide/                      # Architecture, workflows, and getting started
-│   ├── cli/                        # Comprehensive CLI reference manual
+│   ├── introduction/               # Welcome, Why rnex?, Quick Start, and Pure Examples
+│   ├── documentation/              # Architecture, Configuration, Workflows, Lifecycle, Plugins
+│   ├── reference/                  # CLI Reference, RNEX Hooks, Git Hooks, and Environment
 │   ├── plugins/                    # Scoped plugin guides and specifications
-│   ├── examples/                   # Multi-repo patterns and case studies
-│   └── faq/                        # Frequently Asked Questions
+│   └── faq/                        # Frequently Asked Questions & Troubleshooting
 ├── .github/
 │   └── workflows/ci.yml            # GitHub Actions CI workflow
 ├── scripts/

package/lib/commands/init.sh

@@ -170,6 +170,13 @@ git:
   hooks:
 $_hooks_block
 
+# RNEX Lifecycle Hooks
+rnex_hooks:
+  before_sync: []
+  after_sync: []
+  before_clone: []
+  after_clone: []
+
 # Workspace plugins
 plugins:
 $(printf '%b' "$_init_plugins")

package/lib/commands/plugin.sh

@@ -28,6 +28,19 @@ cmd_plugin_list() {
       printf '  %b[available]%b %b%-15s%b %b(v%s)%b - %s\n' \
         "$_DIM" "$_NC" "$_BOLD" "$_name" "$_NC" "$_DIM" "${_version:-0.1.0}" "$_NC" "$_desc"
     fi
+
+    _pcmds="$(plugin_list_commands "$_name" 2>/dev/null || true)"
+    if [ -n "$_pcmds" ]; then
+      echo "$_pcmds" | while read -r _c; do
+        [ -n "$_c" ] || continue
+        _cdesc="$(plugin_get_command_desc "$_name" "$_c" 2>/dev/null || true)"
+        if [ -n "$_cdesc" ]; then
+          printf '                 %b↳ rnex plugin %s %-10s%b %s\n' "$_DIM" "$_name" "$_c" "$_NC" "$_cdesc"
+        else
+          printf '                 %b↳ rnex plugin %s %s%b\n' "$_DIM" "$_name" "$_c" "$_NC"
+        fi
+      done
+    fi
   done
   printf '\n'
   log_dim "To enable a plugin:  rnex plugin enable <name>"
@@ -284,13 +297,31 @@ cmd_plugin() {
       ;;
     enable|install)
       shift
+      _h_pname=""
+      for _arg in "$@"; do
+        case "$_arg" in --*) ;; *) _h_pname="$_arg" ;; esac
+      done
+      RNEX_PLUGIN_NAME="$_h_pname"
+      export RNEX_PLUGIN_NAME
+      run_hook "before_plugin_enable" "$@"
       cmd_plugin_enable "$@"
-      return $?
+      _rc=$?
+      [ "$_rc" -eq 0 ] && run_hook "after_plugin_enable" "$@"
+      return "$_rc"
       ;;
     disable|uninstall|remove)
       shift
+      _h_pname=""
+      for _arg in "$@"; do
+        case "$_arg" in --*) ;; *) _h_pname="$_arg" ;; esac
+      done
+      RNEX_PLUGIN_NAME="$_h_pname"
+      export RNEX_PLUGIN_NAME
+      run_hook "before_plugin_disable" "$@"
       cmd_plugin_disable "$@"
-      return $?
+      _rc=$?
+      [ "$_rc" -eq 0 ] && run_hook "after_plugin_disable" "$@"
+      return "$_rc"
       ;;
     update|upgrade)
       shift

package/lib/commands/repo.sh

@@ -10,12 +10,57 @@ cmd_repo() {
   _subcmd="$1"
   shift
   case "$_subcmd" in
-    add)            cmd_repo_add "$@" ;;
-    remove|rm)      cmd_repo_remove "$@" ;;
-    set)            cmd_repo_set "$@" ;;
-    clone)          cmd_repo_clone "$@" ;;
-    status)         cmd_repo_status "$@" ;;
-    exec)           cmd_repo_exec "$@" ;;
+    add)
+      run_hook "before_repo_add" "$@"
+      cmd_repo_add "$@"
+      _rc=$?
+      [ "$_rc" -eq 0 ] && run_hook "after_repo_add" "$@"
+      return "$_rc"
+      ;;
+    remove|rm)
+      for _arg in "$@"; do
+        case "$_arg" in
+          -*) ;;
+          *) export RNEX_REPO_NAME="$_arg"; break ;;
+        esac
+      done
+      run_hook "before_repo_remove" "$@"
+      cmd_repo_remove "$@"
+      _rc=$?
+      [ "$_rc" -eq 0 ] && run_hook "after_repo_remove" "$@"
+      return "$_rc"
+      ;;
+    set)
+      for _arg in "$@"; do
+        case "$_arg" in
+          -*) ;;
+          *) export RNEX_REPO_NAME="$_arg"; break ;;
+        esac
+      done
+      run_hook "before_repo_set" "$@"
+      cmd_repo_set "$@"
+      _rc=$?
+      [ "$_rc" -eq 0 ] && run_hook "after_repo_set" "$@"
+      return "$_rc"
+      ;;
+    clone)
+      [ $# -gt 0 ] && export RNEX_REPO_NAME="$1"
+      run_hook "before_clone" "$@"
+      cmd_repo_clone "$@"
+      _rc=$?
+      [ "$_rc" -eq 0 ] && run_hook "after_clone" "$@"
+      return "$_rc"
+      ;;
+    status)
+      cmd_repo_status "$@"
+      ;;
+    exec)
+      run_hook "before_exec" "$@"
+      cmd_repo_exec "$@"
+      _rc=$?
+      run_hook "after_exec" "$@"
+      return "$_rc"
+      ;;
     list|ls)        cmd_list "$@" ;;
     help|-h|--help) cmd_repo_help ;;
     *)              die "Unknown repo subcommand: $_subcmd (try 'rnex repo help')" ;;
@@ -115,6 +160,7 @@ cmd_repo_add() {
 
   [ -n "$_name" ] || die "Could not determine repository name from '$_url'"
   [ -n "$_url" ] || die "Usage: rnex repo add <url> [--name <name>] [--branch <branch>] [--local] [--disabled] [--readonly]"
+  export RNEX_REPO_NAME="$_name"
 
   ensure_repos_dir
   _target_dir="$(resolve_repo_path "$_name")"
@@ -392,10 +438,17 @@ cmd_repo_exec() {
   _repo_dir="$(resolve_repo_path "$_name")"
   [ -d "$_repo_dir" ] || die "Repo '$_name' is not cloned yet at $_repo_dir"
 
+  _b="$(git -C "$_repo_dir" symbolic-ref --short HEAD 2>/dev/null || git -C "$_repo_dir" rev-parse --short HEAD 2>/dev/null || true)"
   _cmd="$*"
   printf '%b[%s]%b %s\n' "$_B" "$_name" "$_NC" "$_cmd"
   printf '%s\n' "----------------------------------------"
-  (cd "$_repo_dir" && eval "$_cmd")
+  (
+    RNEX_REPO_NAME="$_name"
+    RNEX_REPO_PATH="$_repo_dir"
+    RNEX_REPO_BRANCH="$_b"
+    export RNEX_REPO_NAME RNEX_REPO_PATH RNEX_REPO_BRANCH
+    cd "$_repo_dir" && eval "$_cmd"
+  )
 }
 
 # Clone all enabled repositories declared in configuration that are not yet cloned.
@@ -481,7 +534,14 @@ cmd_exec() {
 
     printf '\n%b[%s]%b %s\n' "$_B" "$_name" "$_NC" "$_cmd"
     printf '%s\n' "----------------------------------------"
-    if (cd "$_repo_dir" && eval "$_cmd"); then
+    _b="$(git -C "$_repo_dir" symbolic-ref --short HEAD 2>/dev/null || git -C "$_repo_dir" rev-parse --short HEAD 2>/dev/null || true)"
+    if (
+      RNEX_REPO_NAME="$_name"
+      RNEX_REPO_PATH="$_repo_dir"
+      RNEX_REPO_BRANCH="$_b"
+      export RNEX_REPO_NAME RNEX_REPO_PATH RNEX_REPO_BRANCH
+      cd "$_repo_dir" && eval "$_cmd"
+    ); then
       printf '%b[✓] %s succeeded%b\n' "$_G" "$_name" "$_NC"
     else
       _rc=$?

package/lib/commands/sync.sh

@@ -83,7 +83,11 @@ cmd_sync() {
   reconcile_gitignore "$NEXUS_DIR"
 
   # 1.2. Reconcile universal workspace instructions in AGENTS.md (permanent main context file)
+  # and all existing permanent provider instructions files
   merge_rnex_instructions "$NEXUS_DIR/AGENTS.md"
+  for _if in CLAUDE.md GEMINI.md CODEX.md .cursorrules .windsurfrules .github/copilot-instructions.md; do
+    [ -f "$NEXUS_DIR/$_if" ] && merge_rnex_instructions "$NEXUS_DIR/$_if"
+  done
 
   # 1.3. Generate auto-sync script (hardcoded harness)
   _write_auto_sync_script "$NEXUS_DIR"

package/lib/commands/system.sh

@@ -105,6 +105,7 @@ cmd_help() {
     plugin install [--local] <name>  Alias for plugin enable
     plugin update [name]    Update enabled plugin(s) from source
     plugin disable [--local] <name>  Disable plugin from workspace
+    plugin <name> <cmd> [options]    Execute a command exposed by an enabled plugin
 
   EXAMPLES
     rnex init                                   # Initialize workspace in current folder
@@ -121,6 +122,8 @@ cmd_help() {
     rnex list                                   # List all member repos and active branches
     rnex status                                 # Inspect workspace configuration and health
     rnex sync                                   # Reconcile all repos, plugins, skills, and .rnex directories
+    rnex plugin karpathy-llm ingest             # Ingest sources into the Karpathy LLM Wiki
+    rnex plugin karpathy-llm lint --strict      # Validate Karpathy LLM Wiki links and limits
     rnex completion zsh                         # Generate Zsh completion script
 
 EOF

package/lib/hooks.sh

@@ -117,6 +117,70 @@ _run_hook_internal() {
       ) || true
     fi
   done
+
+  # 2. Execute configured commands from rnex_hooks.<event_name>
+  if [ -z "$_hook_target_plugin" ]; then
+    _hook_norm="$(printf '%s' "$_hook_phase_cmd" | tr '-' '_')"
+    case ":${RNEX_HOOK_ACTIVE:-}:" in
+      *":${_hook_norm}:"*)
+        # Re-entrant loop guard: skip re-entrant execution of this hook event
+        ;;
+      *)
+        _rnex_cmds="$(yaml_get_rnex_hook_commands "$_hook_norm" 2>/dev/null || true)"
+        if [ -n "$_rnex_cmds" ]; then
+          _prev_active="${RNEX_HOOK_ACTIVE:-}"
+          export RNEX_HOOK_ACTIVE="${RNEX_HOOK_ACTIVE:+${RNEX_HOOK_ACTIVE}:}${_hook_norm}"
+          _is_blocking=0
+          case "$_hook_norm" in
+            before_*) _is_blocking=1 ;;
+          esac
+          _old_ifs="$IFS"
+          IFS='
+'
+          for _rcmd in $_rnex_cmds; do
+            IFS="$_old_ifs"
+            [ -n "$_rcmd" ] || continue
+            if [ "$_is_blocking" -eq 1 ]; then
+              (
+                RNEX_ROOT="$_hook_root"
+                RNEX_CONFIG_MERGED="$_hook_config_merged"
+                RNEX_CMD="$_hook_cmd"
+                RNEX_ARGS="$_hook_args"
+                RNEX_HOOK_EVENT="$_hook_phase_cmd"
+                RNEX_HOOK_ARGS="$_hook_args"
+                RNEX_QUIET="$_hook_quiet"
+                RNEX_PROVIDER_SKILL_DIRS="$_skill_dirs"
+                export RNEX_ROOT RNEX_CONFIG_MERGED RNEX_CMD RNEX_ARGS RNEX_HOOK_EVENT RNEX_HOOK_ARGS RNEX_QUIET RNEX_PROVIDER_SKILL_DIRS RNEX_LIB_DIR NEXUS_DIR WORKSPACE_YAML WORKSPACE_LOCAL_YAML
+                cd "$_hook_root" && eval "$_rcmd"
+              ) || {
+                _cmd_rc=$?
+                export RNEX_HOOK_ACTIVE="$_prev_active"
+                WORKSPACE_LOCAL_YAML="$_old_local_yaml"
+                WORKSPACE_YAML="$_old_yaml"
+                NEXUS_DIR="$_old_nexus"
+                return "$_cmd_rc"
+              }
+            else
+              (
+                RNEX_ROOT="$_hook_root"
+                RNEX_CONFIG_MERGED="$_hook_config_merged"
+                RNEX_CMD="$_hook_cmd"
+                RNEX_ARGS="$_hook_args"
+                RNEX_HOOK_EVENT="$_hook_phase_cmd"
+                RNEX_HOOK_ARGS="$_hook_args"
+                RNEX_QUIET="$_hook_quiet"
+                RNEX_PROVIDER_SKILL_DIRS="$_skill_dirs"
+                export RNEX_ROOT RNEX_CONFIG_MERGED RNEX_CMD RNEX_ARGS RNEX_HOOK_EVENT RNEX_HOOK_ARGS RNEX_QUIET RNEX_PROVIDER_SKILL_DIRS RNEX_LIB_DIR NEXUS_DIR WORKSPACE_YAML WORKSPACE_LOCAL_YAML
+                cd "$_hook_root" && eval "$_rcmd"
+              ) || true
+            fi
+          done
+          IFS="$_old_ifs"
+          export RNEX_HOOK_ACTIVE="$_prev_active"
+        fi
+        ;;
+    esac
+  fi
   WORKSPACE_LOCAL_YAML="$_old_local_yaml"
   WORKSPACE_YAML="$_old_yaml"
   NEXUS_DIR="$_old_nexus"

package/lib/plugins.sh

@@ -751,7 +751,16 @@ run_plugin_command() {
   _rpc_yaml="${WORKSPACE_YAML:-$_rpc_root/${RNEX_CONFIG_FILE:-rnex.yaml}}"
   _rpc_local_yaml="${WORKSPACE_LOCAL_YAML:-${LOCAL_WORKSPACE_YAML:-$_rpc_root/${RNEX_LOCAL_CONFIG_FILE:-.local.rnex.yaml}}}"
   _rpc_lib_dir="${RNEX_LIB_DIR:-$_rpc_root/lib}"
+  _rpc_args="$*"
 
+  RNEX_PLUGIN_NAME="$_rpc_plugin"
+  RNEX_PLUGIN_COMMAND="$_rpc_cmd"
+  RNEX_PLUGIN_ARGS="$_rpc_args"
+  export RNEX_PLUGIN_NAME RNEX_PLUGIN_COMMAND RNEX_PLUGIN_ARGS
+
+  if command -v run_hook >/dev/null 2>&1; then
+    run_hook "before_plugin_command" "$_rpc_plugin" "$_rpc_cmd" "$@"
+  fi
   (
     RNEX_ROOT="$_rpc_root"
     NEXUS_DIR="$_rpc_root"
@@ -760,12 +769,19 @@ run_plugin_command() {
     LOCAL_WORKSPACE_YAML="$_rpc_local_yaml"
     RNEX_LIB_DIR="$_rpc_lib_dir"
     RNEX_PLUGIN_NAME="$_rpc_plugin"
+    RNEX_PLUGIN_COMMAND="$_rpc_cmd"
+    RNEX_PLUGIN_ARGS="$_rpc_args"
     RNEX_PLUGIN_DIR="$_rpc_root/.rnex/plugins/$_rpc_plugin"
-    export RNEX_ROOT NEXUS_DIR WORKSPACE_YAML WORKSPACE_LOCAL_YAML LOCAL_WORKSPACE_YAML RNEX_LIB_DIR RNEX_PLUGIN_NAME RNEX_PLUGIN_DIR
+    export RNEX_ROOT NEXUS_DIR WORKSPACE_YAML WORKSPACE_LOCAL_YAML LOCAL_WORKSPACE_YAML RNEX_LIB_DIR RNEX_PLUGIN_NAME RNEX_PLUGIN_COMMAND RNEX_PLUGIN_ARGS RNEX_PLUGIN_DIR
     if [ -x "$_rpc_script" ]; then
       "$_rpc_script" "$@"
     else
       sh "$_rpc_script" "$@"
     fi
   )
+  _rc=$?
+  if [ "$_rc" -eq 0 ] && command -v run_hook >/dev/null 2>&1; then
+    run_hook "after_plugin_command" "$_rpc_plugin" "$_rpc_cmd" "$@"
+  fi
+  return "$_rc"
 }

package/lib/sdk.sh

@@ -272,6 +272,13 @@ rnex_block_merge() {
 clean_rnex_instructions() {
   _dst="$1"
   [ -f "$_dst" ] || return 0
+
+  # Permanent main context files must NEVER be stripped or deleted
+  case "$(basename "$_dst")" in
+    AGENTS.md|CLAUDE.md|GEMINI.md|CODEX.md|.cursorrules|.windsurfrules|copilot-instructions.md)
+      return 0
+      ;;
+  esac
   if grep -qF "$AI_MARKER_START" "$_dst" 2>/dev/null; then
     _non_rnex="$(awk -v s="$AI_MARKER_START" -v e="$AI_MARKER_END" '
       $0 == s { skip=1; next }

package/lib/workspace.sh

@@ -339,12 +339,12 @@ upgrade_workspace_config() {
     ' "$_f" > "$_tmp" && mv "$_tmp" "$_f"
   fi
 
-  # 4. Remove legacy git_hooks: setting and add structured git: section if missing
-  if grep -qE '^[ ]*(git_hooks|hooks):' "$_f" 2>/dev/null; then
+  # 4. Remove legacy top-level git_hooks: or hooks: setting and add structured git: section if missing
+  if grep -qE '^(git_hooks|hooks):' "$_f" 2>/dev/null; then
     _tmp="$(mktemp)"
     awk '
       /^[ ]*#.*[aA]utomated workspace Git hooks/ { next }
-      /^[ ]*(git_hooks|hooks):/ { next }
+      /^(git_hooks|hooks):/ { next }
       { print }
     ' "$_f" > "$_tmp" && mv "$_tmp" "$_f"
   fi
@@ -368,6 +368,13 @@ upgrade_workspace_config() {
         print "    pre-commit: []"
         print "    pre-push: []"
         print ""
+        print "# RNEX Lifecycle Hooks"
+        print "rnex_hooks:"
+        print "  before_sync: []"
+        print "  after_sync: []"
+        print "  before_clone: []"
+        print "  after_clone: []"
+        print ""
         inserted=1
       }
       { print }
@@ -387,6 +394,13 @@ upgrade_workspace_config() {
           print "      - \"rnex sync --quiet\""
           print "    pre-commit: []"
           print "    pre-push: []"
+          print ""
+          print "# RNEX Lifecycle Hooks"
+          print "rnex_hooks:"
+          print "  before_sync: []"
+          print "  after_sync: []"
+          print "  before_clone: []"
+          print "  after_clone: []"
         }
       }
     ' "$_f" > "$_tmp" && mv "$_tmp" "$_f"

package/lib/yaml.sh

@@ -267,9 +267,11 @@ _yaml_git_ignore_from_file() {
     function unquote(v) {
       sub(/^[ \t]+/, "", v)
       if (v ~ /^"/) {
-        v = substr(v, 2); sub(/".*$/, "", v)
+        sub(/^"/, "", v)
+        sub(/"[ \t]*(#.*)?$/, "", v)
       } else if (v ~ /^\047/) {
-        v = substr(v, 2); sub(/\047.*$/, "", v)
+        sub(/^\047/, "", v)
+        sub(/\047[ \t]*(#.*)?$/, "", v)
       } else {
         sub(/[ \t]+#.*$/, "", v)
         sub(/[ \t]+$/, "", v)
@@ -391,9 +393,11 @@ _yaml_git_hook_commands_from_file() {
     function unquote(v) {
       sub(/^[ \t]+/, "", v)
       if (v ~ /^"/) {
-        v = substr(v, 2); sub(/".*$/, "", v)
+        sub(/^"/, "", v)
+        sub(/"[ \t]*(#.*)?$/, "", v)
       } else if (v ~ /^\047/) {
-        v = substr(v, 2); sub(/\047.*$/, "", v)
+        sub(/^\047/, "", v)
+        sub(/\047[ \t]*(#.*)?$/, "", v)
       } else {
         sub(/[ \t]+#.*$/, "", v)
         sub(/[ \t]+$/, "", v)
@@ -476,6 +480,157 @@ yaml_get_git_hook_commands() {
   fi
 }
 
+# ---- RNEX Lifecycle Hooks Configuration Operations (rnex_hooks) -------------
+
+# Extract list of hook/event names defined under rnex_hooks from a YAML file.
+_yaml_rnex_hooks_list_from_file() {
+  _yrhl_f="$1"
+  [ -f "$_yrhl_f" ] || return 0
+  awk '
+    /^[ \t]*(rnex_hooks|rnex-hooks):[ \t]*(#.*)?$/ {
+      in_hooks = 1
+      match($0, /^[ \t]*/)
+      hooks_indent = RLENGTH
+      hook_item_indent = -1
+      next
+    }
+    in_hooks && /^[^ \t#]/ { exit }
+    !in_hooks { next }
+    {
+      match($0, /^[ \t]*/)
+      indent = RLENGTH
+      trimmed = substr($0, indent + 1)
+    }
+    trimmed ~ /^([#]|$)/ { next }
+
+    in_hooks && (indent <= hooks_indent) { exit }
+
+    in_hooks {
+      if (hook_item_indent == -1) {
+        hook_item_indent = indent
+      }
+      if (indent == hook_item_indent) {
+        k = trimmed
+        sub(/:.*/, "", k)
+        gsub(/^["\047]|["\047]$/, "", k)
+        gsub(/[[:space:]]/, "", k)
+        gsub(/-/, "_", k)
+        if (length(k) > 0) print k
+      }
+    }
+  ' "$_yrhl_f"
+}
+
+# Enumerate configured hook names under rnex_hooks merged from rnex.yaml and .local.rnex.yaml.
+yaml_list_rnex_hooks() {
+  _yaml_resolve_files
+  {
+    _yaml_rnex_hooks_list_from_file "$_wy"
+    _yaml_rnex_hooks_list_from_file "$_wly"
+  } | awk '!seen[$0]++'
+}
+
+# Extract command list for a specific hook under rnex_hooks.<event_name> from a YAML file.
+# Supports both underscore and hyphenated keys (e.g. after_sync or after-sync).
+_yaml_rnex_hook_commands_from_file() {
+  _yrhc_f="$1"; _yrhc_hook="$2"
+  [ -f "$_yrhc_f" ] || return 0
+  awk -v target_hook="$_yrhc_hook" '
+    function unquote(v) {
+      sub(/^[ \t]+/, "", v)
+      if (v ~ /^"/) {
+        sub(/^"/, "", v)
+        sub(/"[ \t]*(#.*)?$/, "", v)
+      } else if (v ~ /^\047/) {
+        sub(/^\047/, "", v)
+        sub(/\047[ \t]*(#.*)?$/, "", v)
+      } else {
+        sub(/[ \t]+#.*$/, "", v)
+        sub(/[ \t]+$/, "", v)
+      }
+      return v
+    }
+    BEGIN {
+      target_norm = target_hook
+      gsub(/-/, "_", target_norm)
+    }
+    /^[ \t]*(rnex_hooks|rnex-hooks):[ \t]*(#.*)?$/ {
+      in_hooks = 1
+      match($0, /^[ \t]*/)
+      hooks_indent = RLENGTH
+      next
+    }
+    in_hooks && /^[^ \t#]/ { exit }
+    !in_hooks { next }
+    {
+      match($0, /^[ \t]*/)
+      indent = RLENGTH
+      trimmed = substr($0, indent + 1)
+    }
+    trimmed ~ /^([#]|$)/ { next }
+
+    in_hook_cmds {
+      if (indent > target_indent || (indent == target_indent && trimmed ~ /^-([ \t]|$)/)) {
+        if (trimmed ~ /^-([ \t]|$)/) {
+          item = unquote(substr(trimmed, 2))
+          if (length(item) > 0) print item
+        }
+        next
+      }
+      exit
+    }
+
+    in_hooks && (indent <= hooks_indent) { exit }
+
+    in_hooks {
+      k = trimmed
+      sub(/:.*/, "", k)
+      gsub(/^["\047]|["\047]$/, "", k)
+      gsub(/[[:space:]]/, "", k)
+      k_norm = k
+      gsub(/-/, "_", k_norm)
+      if (k_norm == target_norm && trimmed ~ /:[ \t]*/) {
+        target_indent = indent
+        val = trimmed
+        sub(/^[^:]*:[ \t]*/, "", val)
+        if (val ~ /^(#.*)?$/) {
+          in_hook_cmds = 1
+          next
+        }
+        if (val ~ /^\[/) {
+          sub(/^\[/, "", val)
+          sub(/\][ \t]*(#.*)?$/, "", val)
+          n = split(val, parts, ",")
+          for (i = 1; i <= n; i++) {
+            item = unquote(parts[i])
+            if (length(item) > 0) print item
+          }
+          exit
+        }
+        item = unquote(val)
+        if (length(item) > 0) print item
+        exit
+      }
+    }
+  ' "$_yrhc_f"
+}
+
+# Read command list for a specific hook under rnex_hooks.<event_name>
+# supporting both underscore and hyphenated event keys (e.g. after_sync and after-sync),
+# with .local.rnex.yaml override priority.
+yaml_get_rnex_hook_commands() {
+  _event_name="$1"
+  _event_norm="$(printf '%s' "$_event_name" | tr '-' '_')"
+  _yaml_resolve_files
+  if [ -f "$_wly" ] && _yaml_rnex_hooks_list_from_file "$_wly" | grep -qx "$_event_norm"; then
+    _yaml_rnex_hook_commands_from_file "$_wly" "$_event_norm"
+    return 0
+  fi
+  if [ -f "$_wy" ]; then
+    _yaml_rnex_hook_commands_from_file "$_wy" "$_event_norm"
+  fi
+}
+
 # ---- Plugin Configuration Operations ---------------------------------------
 
 _yaml_list_plugins_from_file() {
@@ -516,9 +671,11 @@ _yaml_plugin_list_from_file() {
     function unquote(v) {
       sub(/^[ \t]+/, "", v)
       if (v ~ /^"/) {
-        v = substr(v, 2); sub(/".*$/, "", v)
+        sub(/^"/, "", v)
+        sub(/"[ \t]*(#.*)?$/, "", v)
       } else if (v ~ /^\047/) {
-        v = substr(v, 2); sub(/\047.*$/, "", v)
+        sub(/^\047/, "", v)
+        sub(/\047[ \t]*(#.*)?$/, "", v)
       } else {
         sub(/[ \t]+#.*$/, "", v)
         sub(/[ \t]+$/, "", v)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-nexus",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Lightweight, zero-dependency Virtual Meta-Repo companion for multi-repo workspaces and shared AI context (no git submodules)",
   "bin": {
     "repo-nexus": "rnex",
@@ -50,7 +50,9 @@
     "linux"
   ],
   "devDependencies": {
-    "vitepress": "^1.6.4"
+    "mermaid": "^11.17.2",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-mermaid": "^2.0.17"
   },
   "overrides": {
     "esbuild": "^0.25.0",

package/templates/rnex.example.yaml

@@ -1,188 +1,109 @@
 # ==============================================================================
-# rnex.yaml — Repo Nexus Workspace Configuration (Full Example)
+# rnex.yaml — Repo Nexus Workspace Configuration (Exhaustive Schema Showcase)
 # ==============================================================================
-# This file is the central team manifest for a Repo Nexus workspace (committed to Git).
+# Central team manifest for a Repo Nexus workspace (committed to Git).
 #
 # TWO-LEVEL CONFIGURATION:
-#   1. Repo Config (rnex.yaml): Shared across team, tracks member repos, URLs, plugins.
-#   2. Local Config (.local.rnex.yaml): Machine-specific (gitignored, highest priority),
-#      overrides enable/disable states, URLs, or local developer settings.
-#
-# Place it in your workspace root directory and run `rnex sync` to apply.
-#
-# For more information: https://github.com/unoxen/repo-nexus
-
-# ------------------------------------------------------------------------------
-# version — Workspace configuration schema version
-# ------------------------------------------------------------------------------
-# Used by `rnex sync` to safely detect and reconcile configuration
-# and routing instructions across CLI releases.
-#
-version: 0.8.0
-
-# ------------------------------------------------------------------------------
-# repos_dir — Directory for member repository clones
-# ------------------------------------------------------------------------------
-# Default: ./repos (ignored by Git in the workspace .gitignore)
-#
-# Examples:
-#   repos_dir: ./repos              # relative (recommended)
-#   repos_dir: ./custom-repos       # custom relative path
+#   1. Team Manifest (rnex.yaml): Shared across team, tracks member repos, URLs, plugins.
+#   2. Local Overrides (.local.rnex.yaml): Machine-specific (gitignored, highest priority),
+#      overrides enable/disable states, URLs, read-only flags, or developer settings.
 
-repos_dir: ./repos
+# Workspace Metadata
+version: "1"
+name: "acme-platform"
+description: "Multi-repo platform workspace and shared AI context"
+repos_dir: "./repos"
+code_workspace: "acme.code-workspace"
 
-# ------------------------------------------------------------------------------
-# code_workspace — VS Code / Cursor multi-root workspace file
-# ------------------------------------------------------------------------------
-# Automatically generates and maintains a multi-root .code-workspace file mapping
-# the workspace root and all active member repository clones.
-#
-# Default: false
-#
-# Examples:
-#   code_workspace: false                    # disabled (default)
-#   code_workspace: true                     # generates <workspace-name>.code-workspace
-#   code_workspace: workspace.code-workspace # custom filename
-#
-code_workspace: false
-
-# ------------------------------------------------------------------------------
-# git — Git Integration (Ignore rules & Git hooks)
-# ------------------------------------------------------------------------------
-# git.ignore: list of patterns added to .gitignore (directories starting with
-# .rnex or rnex are recursively ignored by default with trailing slashes).
-# git.hooks: mapping of hook names (post-merge, post-checkout, pre-commit, pre-push)
-# to command lists executed by the native Git hooks.
-#
+# Git Integration (Ignore rules & Git hooks)
 git:
   ignore:
     - "repos/"
     - "**/.rnex*/"
     - "**/rnex*/"
+    - "*.log"
+    - ".env.local"
   hooks:
     post-merge:
       - "rnex sync --quiet"
     post-checkout:
       - "rnex sync --quiet"
-    pre-commit: []
-    pre-push: []
-
-# ------------------------------------------------------------------------------
-# plugins — Workspace plugins, tool integrations, and AI instruction packs
-# ------------------------------------------------------------------------------
-# Plugins extend your workspace with curated AI guidelines, context rules,
-# tool provider integrations (e.g. GitHub Copilot), and templates.
-#
-# Manage plugins with:
-#   rnex plugin list                     # View available and active plugins
-#   rnex plugin enable [--local] <name>  # Enable plugin (global or local override)
-#   rnex plugin disable [--local] <name> # Disable plugin from workspace
-#   rnex plugin info <name>              # View plugin details & configurable options
-#   rnex plugin <name> <cmd> [options]   # Run plugin CLI subcommand (e.g. karpathy-llm lint)
-#
-# Built-in plugins:
-#   claude         — Anthropic Claude Code integration: manages CLAUDE.md; generates user skills in .claude/skills/
-#   codex          — OpenAI Codex integration: manages CODEX.md; generates user skills in .codex/skills/
-#   copilot        — GitHub Copilot integration: manages .github/copilot-instructions.md; generates user skills in .github/skills/
-#   cursor         — Cursor IDE integration: manages .cursorrules & .cursor/rules/; generates user skills in .cursor/rules/
-#   gemini         — Google Gemini / Antigravity integration: manages GEMINI.md; generates user skills in .agents/skills/
-#   windsurf       — Windsurf IDE integration: manages .windsurfrules; generates user skills in .windsurf/rules/
-#   karpathy-llm   — Andrej Karpathy's agent behavioral principles,
-#                    context engineering guidelines, and LLM Wiki architecture
-#
-# Note on AI Architecture:
-#   AGENTS.md at workspace root is the universal cross-tool standard. Assistants that read AGENTS.md
-#   all the time need no separate top-level instructions file. Assistants with native
-#   formats (Claude with CLAUDE.md, Codex with CODEX.md, Gemini with GEMINI.md, Cursor with .cursorrules, Windsurf with .windsurfrules)
-#   have their instruction files maintained automatically when their plugin is enabled.
-#   Agentic skills live self-contained inside .rnex/skills/ (core) and .rnex/plugins/<plugin>/skills/ (plugins).
-#   Provider plugins generate zero-logic User Skills (prefixed with rnex-) into IDE-specific skill directories
-#   linking directly to the agentic skill protocols inside .rnex/.
-
-plugins:
-  # claude:
-  #   skills: true              # generate user skills in .claude/skills/ (default: true)
-  #   instructions: true        # maintain routing instructions in CLAUDE.md (default: true)
-  #   auto_sync_on: SessionStart # trigger auto-sync on lifecycle event (default: SessionStart, or false)
-  #
-  # codex:
-  #   skills: true              # generate user skills in .codex/skills/ (default: true)
-  #   instructions: true        # maintain routing instructions in CODEX.md (default: true)
-  #
-  # copilot:
-  #   skills: true              # generate user skills in .github/skills/ (default: true)
-  #   instructions: true        # maintain routing instructions in .github/copilot-instructions.md (default: true)
-  #
-  # cursor:
-  #   skills: true              # generate user skills in .cursor/rules/ (default: true)
-  #   instructions: true        # maintain routing instructions in .cursorrules (default: true)
-  #
-  # gemini:
-  #   skills: true              # generate user skills in .agents/skills/ (default: true)
-  #   instructions: true        # maintain routing instructions in GEMINI.md (default: true)
-  #   auto_sync_on: SessionStart # trigger auto-sync on lifecycle event (default: SessionStart, or false)
-  #
-  # windsurf:
-  #   skills: true              # generate user skills in .windsurf/rules/ (default: true)
-  #   instructions: true        # maintain routing instructions in .windsurfrules (default: true)
-  #
-  # karpathy-llm:
-  #   wiki_dir: "wiki"          # Directory for curated atomic markdown pages (default: wiki)
-  #   sources:                  # Intake documents: directories and/or glob patterns (default below)
-  #     - docs                  #   directory: all files (hidden dirs and node_modules pruned)
-  #     - "repos/**/README.md"  #   recursive glob (quote it); disabled repos are excluded
-  #                             # A sources list in .local.rnex.yaml replaces this list entirely.
-
+    pre-commit:
+      - "rnex plugin karpathy-llm lint"
+    pre-push:
+      - "rnex plugin karpathy-llm lint --strict"
 
-# ------------------------------------------------------------------------------
-# repos — Member repositories managed by Repo Nexus
-# ------------------------------------------------------------------------------
-# Each repo has:
-#   url:       Git repository URL (SSH or HTTPS).
-#   branch:    Branch to checkout and track (optional).
-#   enabled:   true (default) keeps the repo active in workspace.
-#              false disables the repo (skipped by rnex clone, rnex exec, etc.).
-#              Can be overridden locally in .local.rnex.yaml.
-#   readonly:  false (default) allows normal active development and modifications.
-#              true designates the repository as read-only (used only for information).
-#              AI coding assistants and tools use this repository strictly for reference,
-#              context, and type definitions without modifying or committing code.
-#
-# Examples:
-#   backend:
-#     url: git@github.com:myorg/backend-api.git
-#     branch: main
-#     enabled: true        # default
-#     readonly: false      # default
-#
-#   frontend:
-#     url: https://github.com/myorg/web-app.git
-#     branch: develop
-#     enabled: true
-#
-#   docs-reference:
-#     url: git@github.com:myorg/docs-reference.git
-#     readonly: true       # information-only repository
-#     enabled: true
-#
-#   analytics:
-#     url: git@github.com:myorg/analytics.git
-#     enabled: false       # disabled: skipped by clone & exec
+# RNEX Lifecycle Hooks (Map of RNEX events to command lists)
+rnex_hooks:
+  before_init: []
+  after_init:
+    - "echo 'Workspace initialized'"
+  before_sync: []
+  after_sync:
+    - "rnex plugin karpathy-llm ingest --quiet"
+  before_clone: []
+  after_clone:
+    - "rnex exec npm install"
+  before_repo_add: []
+  after_repo_add: []
+  before_repo_remove: []
+  after_repo_remove: []
+  before_repo_set: []
+  after_repo_set: []
+  before_plugin_enable: []
+  after_plugin_enable: []
+  before_plugin_disable: []
+  after_plugin_disable: []
+  before_plugin_command: []
+  after_plugin_command: []
+  before_exec: []
+  after_exec: []
 
+# Member Repositories
 repos:
-  # backend:
-  #   url: git@github.com:myorg/backend-api.git
-  #   branch: main
-  #   readonly: false
-  #
-  # frontend:
-  #   url: https://github.com/myorg/web-app.git
-  #   branch: develop
-  #
-  # docs-reference:
-  #   url: git@github.com:myorg/docs-reference.git
-  #   readonly: true
-  #
-  # analytics:
-  #   url: git@github.com:myorg/analytics.git
-  #   enabled: false
+  backend:
+    url: "git@github.com:acme/backend-api.git"
+    branch: "main"
+    enabled: true
+    readonly: false
+    description: "Core Go/PostgreSQL API service"
+  frontend:
+    url: "https://github.com/acme/web-client.git"
+    branch: "develop"
+    enabled: true
+    readonly: false
+    description: "React/TypeScript web application"
+  shared-contracts:
+    url: "git@github.com:acme/contracts.git"
+    branch: "v2"
+    enabled: true
+    readonly: true
+    description: "Read-only OpenAPI & Protobuf schemas"
+
+# Scoped Plugins & AI Providers
+plugins:
+  claude:
+    enabled: true
+    skills: true
+  cursor:
+    enabled: true
+    skills: true
+  codex:
+    enabled: true
+    skills: true
+  gemini:
+    enabled: false
+    skills: true
+  windsurf:
+    enabled: false
+    skills: true
+  copilot:
+    enabled: false
+    skills: true
+  karpathy-llm:
+    enabled: true
+    wiki_dir: "wiki"
+    sources:
+      - "docs"
+      - "adr"
+      - "repos/**/README.md"

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

@@ -34,8 +34,8 @@ When working in a workspace with an active Karpathy LLM Wiki:
 - **Bounded Hot Cache**: `<wiki_dir>/hot.md` enforces a strict ~500-word ceiling with 3 structured sections: 1. Architecture & Repo Map, 2. Current Focus & Recent Ingests, 3. Key Contracts. Ingest and lint workflows must condense older context to prevent bloat.
 - **Behavioral Principles**: Strictly adhere to the coding agent principles defined at `.rnex/plugins/karpathy-llm/rules/behavioral.md`.
 - **Annotated Indexing**: `<wiki_dir>/index.md` entries must maintain a single 1-line summary next to each atomic page link (e.g. `- [Auth Flow](auth.md): JWT validation and token rotation`) so agents pinpoint target pages in a single read without trial-and-error scanning.
-- **Ingestion**: When files appear in configured `sources` or member repositories are added, execute the `wiki-ingest` agentic skill protocol (`.rnex/plugins/karpathy-llm/skills/wiki-ingest.md`). One source document produces 5–25 atomic pages — never collapse a source into a single file.
-- **Maintenance**: Execute the `wiki-lint` agentic skill protocol (`.rnex/plugins/karpathy-llm/skills/wiki-lint.md`) to validate paths, update `mentioned_in`, and preserve graph integrity.
+- **Ingestion**: When files appear in configured `sources` or member repositories are added, execute `rnex plugin karpathy-llm ingest` or the `wiki-ingest` agentic skill protocol (`.rnex/plugins/karpathy-llm/skills/wiki-ingest.md`). One source document produces 5–25 atomic pages — never collapse a source into a single file.
+- **Maintenance**: Execute `rnex plugin karpathy-llm lint` or the `wiki-lint` agentic skill protocol (`.rnex/plugins/karpathy-llm/skills/wiki-lint.md`) to validate paths, update `mentioned_in`, and preserve graph integrity.
 
 ---
 

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

@@ -8,6 +8,14 @@ Universal agentic skill protocol for decomposing and ingesting raw source materi
 
 Use this skill when ingesting new reference materials, architecture documentation, transcripts, articles, or member repository READMEs into the workspace curated wiki knowledge graph.
 
+## CLI Helper
+
+You can also invoke the built-in deterministic ingest helper directly from the terminal:
+
+```sh
+rnex plugin karpathy-llm ingest [--source <path>] [--repo <name>] [--quiet]
+```
+
 ## Ingestion Protocol
 
 1. **Resolve Configuration & Direct Source Paths:**

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

@@ -8,6 +8,14 @@ Universal agentic skill protocol for maintaining Karpathy LLM Wiki graph integri
 
 Use this skill to perform health checks and maintenance on the curated wiki knowledge graph, resolve broken links, recompute bidirectional relations, and preserve the ~500-word hot cache boundary.
 
+## CLI Helper
+
+You can also invoke the built-in deterministic lint helper directly from the terminal:
+
+```sh
+rnex plugin karpathy-llm lint [--strict] [--quiet]
+```
+
 ## Maintenance Protocol
 
 1. **Resolve Configuration & Verify Paths:**