repo-nexus 0.8.7 → 0.8.8

package/README.md

@@ -49,7 +49,7 @@ A **Virtual Meta-Repo** companion for multi-repo workspaces and shared AI contex
 
 | What It Is | What It Isn't |
 | :--- | :--- |
-| **A lightweight companion utility** (~25 KB POSIX script). | **NOT a replacement for your workspace or tools.** It doesn't replace VS Code, Cursor, JetBrains, or your terminal. |
+| **A lightweight companion utility** (modular pure POSIX `/bin/sh` CLI). | **NOT a replacement for your workspace or tools.** It doesn't replace VS Code, Cursor, JetBrains, or your terminal. |
 | **A Virtual Meta-Repo orchestrator** managing member clones in `./repos/`. | **NOT a build tool or monorepo orchestrator.** It doesn't 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. |
 | **Strictly encapsulated.** Internal rnex assets live exclusively in `.rnex/`. | **NOT invasive.** Member repositories remain clean; workspace-related context is isolated to `repos/<name>/.rnex/`. |
@@ -134,10 +134,21 @@ All declared member repositories are cloned and wired up automatically!
 
 ## Project Structure
 
-```
+```text
 repo-nexus/
 ├── package.json                    # npm package manifest (single version source of truth)
-├── rnex                            # CLI executable (POSIX shell)
+├── rnex                            # CLI entrypoint (pure POSIX /bin/sh)
+├── lib/                            # Modular POSIX shell libraries
+│   ├── core.sh                     # Terminal colors, logging, path & version helpers
+│   ├── yaml.sh                     # Two-level YAML parser & config mutators
+│   ├── workspace.sh                # Workspace root discovery & auto-sync engine
+│   ├── repos.sh                    # Member repo path resolution & on-demand .rnex/
+│   ├── plugins.sh                  # Plugin discovery, template & command engine
+│   ├── sdk.sh                      # Plugin Hook SDK & User Skill generator
+│   ├── ai.sh                       # AI routing instructions, .gitignore & .code-workspace
+│   ├── hooks.sh                    # Declarative Git hooks & lifecycle event dispatcher
+│   ├── commands.sh                 # CLI subcommand module loader
+│   └── commands/                   # Subcommand implementations (init, sync, repo, etc.)
 ├── AGENTS.md                       # Routing-only universal AI instructions
 ├── CHANGELOG.md                    # Release history and migration notes
 ├── CONTRIBUTION.md                 # POSIX standards, testing setup, and plugin contract
@@ -158,9 +169,9 @@ repo-nexus/
 ├── tests/
 │   ├── test_cli.sh                 # Main test runner
 │   ├── test_helper.sh              # Shared test harness and utilities
-│   └── suites/                     # Modular test suites
+│   └── suites/                     # Modular test suites (01–07)
 ├── toolkit/                        # Built-in plugins and core agentic skills
-│   ├── plugins/                    # Scoped workspace plugins
+│   ├── plugins/                    # Scoped workspace & AI provider plugins
 │   └── skills/                     # Core workspace agentic skills
 └── README.md
 ```

package/lib/ai.sh

@@ -6,16 +6,14 @@
 
 # ---- Gitignore & Search Tool Ignore Reconciliation -------------------------
 
-# Reconcile workspace root .gitignore and .ignore:
-# - Ensures repos/ is ignored in git to prevent accidental commits of member repos
-# - Ensures .local.rnex.yaml is ignored
-# - Ensures .ignore un-ignores repos/* so ripgrep and AI tools can index member files
-reconcile_gitignore() {
-  _dir="${1:-$NEXUS_DIR}"
-  _gi="$_dir/.gitignore"
-
-  if [ ! -f "$_gi" ]; then
-    cat > "$_gi" <<GI_EOF
+GITIGNORE_MARKER_START="# REPO-NEXUS:START"
+GITIGNORE_MARKER_END="# REPO-NEXUS:END"
+
+# Emit the delimited Repo Nexus .gitignore section synced with git.ignore configuration.
+_build_rnex_gitignore_section() {
+  cat <<GI_SECTION_EOF
+$GITIGNORE_MARKER_START
+# Managed by Repo Nexus (rnex) — synced with git.ignore in workspace configuration
 # Member repos (managed by rnex, ignored at workspace level)
 repos/*
 !repos/.gitkeep
@@ -29,7 +27,52 @@ rnex*/
 # Local machine-specific configuration
 $RNEX_LOCAL_CONFIG_FILE
 .rnex.local.yaml
-GI_EOF
+GI_SECTION_EOF
+
+  _custom_ignores="$(yaml_get_git_ignore 2>/dev/null || true)"
+  if [ -n "$_custom_ignores" ]; then
+    _added_custom_header=0
+    _seen_custom=""
+    printf '%s\n' "$_custom_ignores" | while IFS= read -r _ci || [ -n "$_ci" ]; do
+      [ -n "$_ci" ] || continue
+      case "$_ci" in
+        "repos/"|"repos/*"|"!repos/.gitkeep"|"**/.rnex*/"|"**/rnex*/"|".rnex*/"|"rnex*/"|"$RNEX_LOCAL_CONFIG_FILE"|".rnex.local.yaml")
+          continue
+          ;;
+      esac
+      case "
+$_seen_custom
+" in
+        *"
+$_ci
+"*) continue ;;
+      esac
+      _seen_custom="${_seen_custom:+$_seen_custom
+}$_ci"
+      if [ "$_added_custom_header" -eq 0 ]; then
+        printf '\n# Custom entries from git.ignore in workspace configuration\n'
+        _added_custom_header=1
+      fi
+      printf '%s\n' "$_ci"
+    done
+  fi
+
+  printf '%s\n' "$GITIGNORE_MARKER_END"
+}
+
+# Reconcile workspace root .gitignore and .ignore:
+# - Maintains a delimited (# REPO-NEXUS:START ... # REPO-NEXUS:END) section in .gitignore
+# - Synchronizes the section with git.ignore from rnex.yaml and .local.rnex.yaml
+# - Preserves user-authored .gitignore rules outside the managed section
+# - Ensures .ignore un-ignores repos/* so ripgrep and AI tools can index member files
+reconcile_gitignore() {
+  _dir="${1:-$NEXUS_DIR}"
+  _gi="$_dir/.gitignore"
+  _sec_tmp="$(mktemp)"
+  _build_rnex_gitignore_section > "$_sec_tmp"
+
+  if [ ! -f "$_gi" ]; then
+    mv "$_sec_tmp" "$_gi"
     log_ok "Created .gitignore (ignoring repos/, recursive .rnex directories, and $RNEX_LOCAL_CONFIG_FILE)"
   else
     # 1. Strip any legacy lint_trigger_counter entries if present
@@ -39,72 +82,192 @@ GI_EOF
       log_ok "Removed legacy lint trigger counter entries from .gitignore"
     fi
 
-    # 2. Strip any legacy un-slashed .rnex or rnex rules that might match files
-    if grep -qE '^[ ]*#?[ ]*Repo Nexus internal state' "$_gi" 2>/dev/null || grep -qE '^(\.rnex|rnex)$' "$_gi" 2>/dev/null; then
+    # 2. If delimited section exists, replace it in-place with the newly synced section
+    if grep -qFx -- "$GITIGNORE_MARKER_START" "$_gi" 2>/dev/null; then
       _tmp="$(mktemp)"
-      grep -vE '(^[ ]*#?[ ]*Repo Nexus internal state|^(\.rnex|rnex)$)' "$_gi" > "$_tmp" && mv "$_tmp" "$_gi"
-    fi
-
-    # 3. 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
+      awk -v s="$GITIGNORE_MARKER_START" -v e="$GITIGNORE_MARKER_END" -v src="$_sec_tmp" '
+        $0 == s {
+          in_b = 1
+          while ((getline line < src) > 0) print line
+          close(src)
+          next
+        }
+        $0 == e {
+          in_b = 0
+          next
+        }
+        !in_b { print }
+      ' "$_gi" > "$_tmp" && mv "$_tmp" "$_gi"
+      rm -f "$_sec_tmp"
+    else
+      # 3. Upgrade legacy un-delimited .gitignore or append managed section to existing user .gitignore
+      _user_tmp="$(mktemp)"
+      awk -v local_cfg="$RNEX_LOCAL_CONFIG_FILE" '
+        /^[ ]*#[ ]*Member repos \(managed by rnex/ { next }
+        /^[ ]*#[ ]*Recursive Repo Nexus directories/ { next }
+        /^[ ]*#?[ ]*Repo Nexus internal state/ { next }
+        /^[ ]*#[ ]*Local machine-specific configuration/ { next }
+        /^[ ]*#[ ]*Custom entries from git\.ignore in workspace configuration/ { next }
+        $0 == "repos/*" || $0 == "!repos/.gitkeep" { next }
+        $0 == "**/.rnex*/" || $0 == "**/rnex*/" || $0 == ".rnex*/" || $0 == "rnex*/" { next }
+        $0 == ".rnex" || $0 == "rnex" { next }
+        $0 == local_cfg || $0 == ".rnex.local.yaml" { next }
+        { lines[++n] = $0 }
+        END {
+          start = 1
+          while (start <= n && lines[start] ~ /^[[:space:]]*$/) start++
+          end = n
+          while (end >= start && lines[end] ~ /^[[:space:]]*$/) end--
+          for (i = start; i <= end; i++) print lines[i]
+        }
+      ' "$_gi" > "$_user_tmp"
 
-    # 4. Ensure recursive directory-only rnex rules are present
-    _added_rnex_rules=0
-    for _pat in "**/.rnex*/" "**/rnex*/" ".rnex*/" "rnex*/"; do
-      if ! grep -qFx -- "$_pat" "$_gi" 2>/dev/null; then
-        if [ "$_added_rnex_rules" -eq 0 ]; then
-          printf '\n# Recursive Repo Nexus directories (trailing slashes prevent ignoring rnex binary or rnex.yaml)\n' >> "$_gi"
-          _added_rnex_rules=1
-        fi
-        printf '%s\n' "$_pat" >> "$_gi"
+      _tmp="$(mktemp)"
+      if [ -s "$_user_tmp" ]; then
+        cat "$_user_tmp" > "$_tmp"
+        printf '\n' >> "$_tmp"
       fi
-    done
-
-    # 5. 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"
+      cat "$_sec_tmp" >> "$_tmp"
+      mv "$_tmp" "$_gi"
+      rm -f "$_user_tmp" "$_sec_tmp"
     fi
   fi
 
-  # 6. Append any custom file and directory patterns from git.ignore
-  _custom_ignores="$(yaml_get_git_ignore 2>/dev/null || true)"
-  if [ -n "$_custom_ignores" ]; then
-    _added_custom_header=0
-    _old_ifs="$IFS"
-    IFS='
-'
-    for _ci in $_custom_ignores; do
-      IFS="$_old_ifs"
-      [ -n "$_ci" ] || continue
-      if [ "$_ci" = "repos/" ] && grep -qFx -- "repos/*" "$_gi" 2>/dev/null; then
-        continue
-      fi
-      if ! grep -qFx -- "$_ci" "$_gi" 2>/dev/null; then
-        if [ "$_added_custom_header" -eq 0 ]; then
-          printf '\n# Custom entries from git.ignore in workspace configuration\n' >> "$_gi"
-          _added_custom_header=1
-        fi
-        printf '%s\n' "$_ci" >> "$_gi"
-      fi
-    done
-    IFS="$_old_ifs"
-  fi
-
   # Universal search tool ignore file (ripgrep, Claude Code, VS Code, Zed)
   ensure_provider_ignore "$_dir/.ignore" \
     "Member repos (un-ignored for ripgrep, Claude Code, VS Code, and search tools)" \
     "Created .ignore (un-ignoring member repos for search tools)"
 }
 
+# Clean managed Repo Nexus ignore block from .gitignore, removing file if empty
+clean_rnex_gitignore() {
+  _dir="${1:-$NEXUS_DIR}"
+  _gi="$_dir/.gitignore"
+  [ -f "$_gi" ] || return 0
+  if grep -qFx -- "${GITIGNORE_MARKER_START:-# REPO-NEXUS:START}" "$_gi" 2>/dev/null; then
+    _user_content="$(awk -v s="${GITIGNORE_MARKER_START:-# REPO-NEXUS:START}" -v e="${GITIGNORE_MARKER_END:-# REPO-NEXUS:END}" '
+      $0 == s { in_b = 1; next }
+      $0 == e { in_b = 0; next }
+      !in_b { print }
+    ' "$_gi" | sed -e '/^[[:space:]]*$/d' -e '/^[[:space:]]*#/d')"
+    if [ -z "$_user_content" ]; then
+      rm -f "$_gi"
+      [ "${RNEX_QUIET:-0}" -eq 0 ] && [ "${_sync_quiet:-0}" -eq 0 ] && log_ok "Removed .gitignore"
+    else
+      _tmp="$(mktemp)"
+      awk -v s="${GITIGNORE_MARKER_START:-# REPO-NEXUS:START}" -v e="${GITIGNORE_MARKER_END:-# REPO-NEXUS:END}" '
+        $0 == s { in_b = 1; next }
+        $0 == e { in_b = 0; next }
+        !in_b { print }
+      ' "$_gi" > "$_tmp" && mv "$_tmp" "$_gi"
+      [ "${RNEX_QUIET:-0}" -eq 0 ] && [ "${_sync_quiet:-0}" -eq 0 ] && log_ok "Removed Repo Nexus rules from .gitignore"
+    fi
+  fi
+}
+
 # ---- AI Instructions Compilation (.rnex/ai-instructions.md) ----------------
 
+# Resolve the primary instruction file for an AI provider plugin
+plugin_get_instruction_file() {
+  _pif_name="$1"
+  _pif_pdir="${2:-}"
+  [ -n "$_pif_pdir" ] || _pif_pdir="$(find_plugin_dir "$_pif_name" 2>/dev/null || true)"
+  _pif_file=""
+  if [ -n "$_pif_pdir" ]; then
+    _pif_file="$(plugin_get_field "$_pif_pdir" "instruction_file" 2>/dev/null || true)"
+  fi
+  if [ -z "$_pif_file" ]; then
+    case "$_pif_name" in
+      claude)   _pif_file="CLAUDE.md" ;;
+      gemini)   _pif_file="GEMINI.md" ;;
+      cursor)   _pif_file=".cursorrules" ;;
+      windsurf) _pif_file=".windsurfrules" ;;
+      codex)    _pif_file="CODEX.md" ;;
+      copilot)  _pif_file=".github/copilot-instructions.md" ;;
+      agents|agent) _pif_file="AGENTS.md" ;;
+    esac
+  fi
+  printf '%s' "$_pif_file"
+}
+
+# Enumerate primary instruction files for currently enabled AI provider plugins
+get_active_provider_instruction_files() {
+  _gap_dir="${1:-$NEXUS_DIR}"
+  _gap_files=""
+  for _p in $(yaml_list_plugins 2>/dev/null || true); do
+    [ -n "$_p" ] || continue
+    yaml_plugin_enabled "$_p" 2>/dev/null || continue
+    _ifile="$(plugin_get_instruction_file "$_p" 2>/dev/null || true)"
+    if [ -n "$_ifile" ]; then
+      case " $_gap_files " in
+        *" $_ifile "*) ;;
+        *) _gap_files="${_gap_files:+$_gap_files }$_ifile" ;;
+      esac
+    fi
+  done
+  printf '%s' "$_gap_files"
+}
+
+# Check if an instruction file contains custom user instructions outside the rnex block
+file_has_user_content() {
+  _fhuc_file="$1"
+  [ -f "$_fhuc_file" ] || return 1
+  _content=""
+  if grep -qF "${AI_MARKER_START:-<!-- REPO-NEXUS:START -->}" "$_fhuc_file" 2>/dev/null; then
+    _content="$(awk -v s="${AI_MARKER_START:-<!-- REPO-NEXUS:START -->}" -v e="${AI_MARKER_END:-<!-- REPO-NEXUS:END -->}" '
+      $0 == s { in_b = 1; next }
+      $0 == e { in_b = 0; next }
+      !in_b { print }
+    ' "$_fhuc_file" | sed -e '/^[[:space:]]*$/d')"
+  else
+    _content="$(grep -v "CRITICAL: You MUST read and strictly follow all instructions in \`.rnex/ai-instructions.md\`" "$_fhuc_file" 2>/dev/null | grep -v "Multi-Repo AI Workspace Context" | sed -e '/^[[:space:]]*$/d')"
+  fi
+  [ -n "$_content" ]
+}
+
+# Reconcile AI provider instruction files:
+# - When provider plugins are enabled (e.g. Gemini, Claude), creates/updates their specific instruction files (GEMINI.md, CLAUDE.md)
+# - Only creates AGENTS.md if it is the main instructions file for an enabled AI provider or no provider plugins are enabled
+# - Cleans up instruction files that have no user content when their provider is disabled or inactive
+reconcile_ai_instructions_files() {
+  _raif_dir="${1:-$NEXUS_DIR}"
+  _active_files="$(get_active_provider_instruction_files "$_raif_dir" 2>/dev/null || true)"
+
+  if [ -n "$_active_files" ]; then
+    # Active AI providers are configured with their own instruction files
+    for _af in $_active_files; do
+      merge_rnex_instructions "$_raif_dir/$_af"
+    done
+
+    # If AGENTS.md is not an active provider instruction file, clean rnex instructions from it
+    # (deleting it if solely rnex-managed, or stripping the rnex block if user content exists)
+    case " $_active_files " in
+      *" AGENTS.md "*) ;;
+      *)
+        if [ -f "$_raif_dir/AGENTS.md" ]; then
+          clean_rnex_instructions "$_raif_dir/AGENTS.md"
+        fi
+        ;;
+    esac
+  else
+    # No provider plugins enabled: AGENTS.md serves as the default main instructions file
+    merge_rnex_instructions "$_raif_dir/AGENTS.md"
+  fi
+
+  # For any existing instruction files on disk that are NOT currently active:
+  # Clean rnex instructions (removing file if empty outside block, or stripping rnex block)
+  for _if in CLAUDE.md GEMINI.md CODEX.md .cursorrules .windsurfrules .github/copilot-instructions.md; do
+    case " $_active_files " in
+      *" $_if "*) ;;
+      *)
+        if [ -f "$_raif_dir/$_if" ]; then
+          clean_rnex_instructions "$_raif_dir/$_if"
+        fi
+        ;;
+    esac
+  done
+}
+
 # Compile the unified .rnex/ai-instructions.md file consumed by AI coding agents.
 # Aggregates sample template instructions and active plugin instruction sections.
 build_ai_instructions() {
@@ -299,21 +462,7 @@ get_active_provider_skill_dirs() {
     [ -n "$_p" ] || continue
     yaml_plugin_enabled "$_p" 2>/dev/null || continue
     if provider_option_enabled "$_p" "skills" 2>/dev/null; then
-      _pdir="$(find_plugin_dir "$_p" 2>/dev/null || true)"
-      _sdir=""
-      if [ -n "$_pdir" ]; then
-        _sdir="$(plugin_get_field "$_pdir" "skill_dir" 2>/dev/null || true)"
-      fi
-      if [ -z "$_sdir" ]; then
-        case "$_p" in
-          copilot)  _sdir=".github/skills" ;;
-          cursor)   _sdir=".cursor/rules" ;;
-          claude)   _sdir=".claude/skills" ;;
-          windsurf) _sdir=".windsurf/rules" ;;
-          gemini)   _sdir=".agents/skills" ;;
-          codex)    _sdir=".codex/skills" ;;
-        esac
-      fi
+      _sdir="$(plugin_get_skill_dir "$_p")"
       if [ -n "$_sdir" ]; then
         case " $_dirs " in
           *" $_sdir "*) ;;

package/lib/commands/init.sh

@@ -194,10 +194,7 @@ YAML_EOF
   WORKSPACE_LOCAL_YAML="$_init_dir/$RNEX_LOCAL_CONFIG_FILE"
 
   # ---- 2. Merge routing instructions into AI instructions files ------------
-  merge_rnex_instructions "$_init_dir/AGENTS.md"
-  for _if in CLAUDE.md GEMINI.md CODEX.md .cursorrules .windsurfrules .github/copilot-instructions.md; do
-    [ -f "$_init_dir/$_if" ] && merge_rnex_instructions "$_init_dir/$_if"
-  done
+  reconcile_ai_instructions_files "$_init_dir"
 
   # ---- 3. Create repos directory with .gitkeep -----------------------------
   _repos_dir="$_init_dir/repos"

package/lib/commands/plugin.sh

@@ -82,15 +82,7 @@ cmd_plugin_info() {
   [ -n "$_home" ] && printf '%bHomepage:%b     %s\n' "$_BOLD" "$_NC" "$_home"
   printf '%bLocation:%b     %s\n' "$_BOLD" "$_NC" "$_pdir"
 
-  _skill_target="$(plugin_get_field "$_pdir" "skill_dir" 2>/dev/null || true)"
-  [ -z "$_skill_target" ] && case "$_name" in
-    copilot)  _skill_target=".github/skills/" ;;
-    claude)   _skill_target=".claude/skills/" ;;
-    gemini)   _skill_target=".agents/skills/" ;;
-    cursor)   _skill_target=".cursor/rules/" ;;
-    windsurf) _skill_target=".windsurf/rules/" ;;
-    codex)    _skill_target=".codex/skills/" ;;
-  esac
+  _skill_target="$(plugin_get_skill_dir "$_name" "$_pdir")"
   case "$_skill_target" in
     */|"") ;;
     *) _skill_target="${_skill_target}/" ;;

package/lib/commands/status.sh

@@ -4,21 +4,7 @@
 # lib/commands/status.sh — Workspace health and status diagnostics
 # ============================================================================
 
-# Query active plugins for any non-manual lint triggers (e.g. git hook triggers).
-_status_active_plugin_trigger() {
-  for _p in $(yaml_list_plugins 2>/dev/null || true); do
-    yaml_plugin_enabled "$_p" 2>/dev/null || continue
-    _trig="$(yaml_plugin_get "$_p" "lint_trigger" 2>/dev/null || true)"
-    [ -z "$_trig" ] && _trig="$(yaml_plugin_get "$_p" "trigger" 2>/dev/null || true)"
-    if [ -n "$_trig" ] && [ "$_trig" != "manual" ]; then
-      printf '%s' "$_trig"
-      return 0
-    fi
-  done
-  return 0
-}
-
-# Check if a directory contains any rnex-* user skills or skill symlinks.
+# Check if a directory contains any rnex-* user skill pointers or skill bundles.
 _status_has_rnex_skills() {
   [ -d "$1" ] && { ls "$1"/rnex-*.md >/dev/null 2>&1 || ls -d "$1"/rnex-* >/dev/null 2>&1; }
 }
@@ -80,15 +66,31 @@ cmd_status() {
   fi
 
   _gi="$NEXUS_DIR/.gitignore"
-  _gi_repos=0; _gi_local=0; _gi_has_counter=0; _gi_has_rnex=0
+  _gi_repos=0; _gi_local=0; _gi_has_counter=0; _gi_has_rnex=0; _gi_has_markers=0; _gi_custom_ok=1
   if [ -f "$_gi" ]; then
     grep -q '^repos' "$_gi" 2>/dev/null && _gi_repos=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
     grep -q '\*\*/\.rnex\*/' "$_gi" 2>/dev/null && _gi_has_rnex=1
+    if grep -qFx -- "${GITIGNORE_MARKER_START:-# REPO-NEXUS:START}" "$_gi" 2>/dev/null && \
+       grep -qFx -- "${GITIGNORE_MARKER_END:-# REPO-NEXUS:END}" "$_gi" 2>/dev/null; then
+      _gi_has_markers=1
+      _gi_exp_tmp="$(mktemp)"
+      _gi_act_tmp="$(mktemp)"
+      _build_rnex_gitignore_section > "$_gi_exp_tmp"
+      awk -v s="${GITIGNORE_MARKER_START:-# REPO-NEXUS:START}" -v e="${GITIGNORE_MARKER_END:-# REPO-NEXUS:END}" '
+        $0 == s { in_b = 1 }
+        in_b { print }
+        $0 == e { in_b = 0; exit }
+      ' "$_gi" > "$_gi_act_tmp"
+      if ! cmp -s "$_gi_exp_tmp" "$_gi_act_tmp"; then
+        _gi_custom_ok=0
+      fi
+      rm -f "$_gi_exp_tmp" "$_gi_act_tmp"
+    fi
   fi
 
-  if [ "$_gi_repos" -eq 1 ] && [ "$_gi_local" -eq 1 ] && [ "$_gi_has_counter" -eq 0 ] && [ "$_gi_has_rnex" -eq 1 ]; then
+  if [ "$_gi_repos" -eq 1 ] && [ "$_gi_local" -eq 1 ] && [ "$_gi_has_counter" -eq 0 ] && [ "$_gi_has_rnex" -eq 1 ] && [ "$_gi_has_markers" -eq 1 ] && [ "$_gi_custom_ok" -eq 1 ]; then
     printf '  %b✓%b Git Ignore:    repos/, %s, and **/.rnex*/ ignored in .gitignore\n' "$_G" "$_NC" "$RNEX_LOCAL_CONFIG_FILE"
   else
     printf '  %b!%b Git Ignore:    recommend running "rnex sync" to update .gitignore (repos/, local configs)\n' "$_Y" "$_NC"
@@ -126,10 +128,11 @@ cmd_status() {
   else
     printf '  %b✗%b %s %b(compiled AI instructions — MISSING; run "rnex sync" to create)%b\n' "$_R" "$_NC" ".rnex/ai-instructions.md" "$_R" "$_NC"
   fi
+
+  _has_any_instructions=0
   if [ -f "$NEXUS_DIR/AGENTS.md" ]; then
     printf '  %b✓%b %s %b(standard instructions directive)%b\n' "$_G" "$_NC" "AGENTS.md" "$_DIM" "$_NC"
-  else
-    printf '  %b✗%b %s %b(standard instructions directive — MISSING; run "rnex sync" to create)%b\n' "$_R" "$_NC" "AGENTS.md" "$_R" "$_NC"
+    _has_any_instructions=1
   fi
   for _pair in \
     "CLAUDE.md:Claude" \
@@ -142,8 +145,15 @@ cmd_status() {
     _ilbl="${_pair#*:}"
     if [ -f "$NEXUS_DIR/$_ifile" ]; then
       printf '  %b✓%b %s %b(%s instructions)%b\n' "$_G" "$_NC" "$_ifile" "$_DIM" "$_ilbl" "$_NC"
+      _has_any_instructions=1
     fi
   done
+  if [ "$_has_any_instructions" -eq 0 ]; then
+    _active_ifiles=""
+    command -v get_active_provider_instruction_files >/dev/null 2>&1 && _active_ifiles="$(get_active_provider_instruction_files "$NEXUS_DIR" 2>/dev/null || true)"
+    _target_ifile="${_active_ifiles:-AGENTS.md}"
+    printf '  %b✗%b %s %b(instructions directive — MISSING; run "rnex sync" to create)%b\n' "$_R" "$_NC" "$_target_ifile" "$_R" "$_NC"
+  fi
   if [ -n "$CODE_WORKSPACE_FILE" ]; then
     if [ -f "$NEXUS_DIR/$CODE_WORKSPACE_FILE" ]; then
       printf '  %b✓%b %s %b(VS Code / Cursor workspace)%b\n' "$_G" "$_NC" "$CODE_WORKSPACE_FILE" "$_DIM" "$_NC"

package/lib/commands/sync.sh

@@ -84,10 +84,7 @@ cmd_sync() {
 
   # 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
+  reconcile_ai_instructions_files "$NEXUS_DIR"
 
   # 1.3. Generate auto-sync script (hardcoded harness)
   _write_auto_sync_script "$NEXUS_DIR"

package/lib/core.sh

@@ -99,7 +99,7 @@ normalize_rel_path() {
 # ---- Version Resolution (package.json is single source of truth) ----------
 
 # Dynamically locate the nearest package.json and extract its "version" field.
-# Falls back to 0.5.1 if package.json cannot be read.
+# Falls back to 0.8.7 if package.json cannot be read.
 resolve_version() {
   _sdir="$(dirname "$SCRIPT_LOCATION")"
   for _cand in "$SCRIPT_LOCATION/package.json" "$_sdir/package.json" "$_sdir/../package.json"; do
@@ -111,7 +111,7 @@ resolve_version() {
       fi
     fi
   done
-  printf '0.5.1'
+  printf '0.8.7'
 }
 
 RNEX_VERSION="$(resolve_version)"

package/lib/hooks.sh

@@ -306,10 +306,7 @@ install_git_hooks() {
   esac
   [ -d "$_git_dir" ] || return 0
   _hooks_dir="$_git_dir/hooks"
-  mkdir -p "$_hooks_dir"
-  for _h in $RNEX_MANAGED_GIT_HOOKS; do
-    _create_hook_script "$_hooks_dir/$_h" "$_h"
-  done
+  _install_managed_hook_scripts "$_hooks_dir"
   # Clean up legacy .rnex/hooks if core.hooksPath was previously set to it
   _hp="$(git -C "$_ws_dir" config --get core.hooksPath 2>/dev/null || true)"
   if [ "$_hp" = ".rnex/hooks" ] || [ "$_hp" = "$_ws_dir/.rnex/hooks" ]; then

package/lib/plugins.sh

@@ -72,6 +72,28 @@ plugin_get_field() {
   ' "$_pdir/plugin.yaml"
 }
 
+# Resolve target user skill directory for a provider plugin from plugin.yaml (with fallback).
+plugin_get_skill_dir() {
+  _pgs_name="$1"
+  _pgs_pdir="${2:-}"
+  [ -n "$_pgs_pdir" ] || _pgs_pdir="$(find_plugin_dir "$_pgs_name" 2>/dev/null || true)"
+  _pgs_dir=""
+  if [ -n "$_pgs_pdir" ]; then
+    _pgs_dir="$(plugin_get_field "$_pgs_pdir" "skill_dir" 2>/dev/null || true)"
+  fi
+  if [ -z "$_pgs_dir" ]; then
+    case "$_pgs_name" in
+      copilot)  _pgs_dir=".github/skills" ;;
+      cursor)   _pgs_dir=".cursor/rules" ;;
+      claude)   _pgs_dir=".claude/skills" ;;
+      windsurf) _pgs_dir=".windsurf/rules" ;;
+      gemini)   _pgs_dir=".agents/skills" ;;
+      codex)    _pgs_dir=".codex/skills" ;;
+    esac
+  fi
+  printf '%s' "$_pgs_dir"
+}
+
 # Parse declared template source-to-destination mappings from plugin.yaml.
 plugin_list_templates() {
   _pdir="$1"
@@ -108,6 +130,9 @@ plugin_resolve_placeholders() {
   _p="$1"; _pd="$2"; _str="$3"
   _res="$(printf '%s' "$_str" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' | tr -d "'\"")"
 
+  # Normalize legacy static prefixes into placeholders prior to expansion
+  _res="$(printf '%s' "$_res" | sed -e 's|^\.\{0,1\}\/\{0,1\}wiki/|{wiki_dir}/|' -e 's|^\.\{0,1\}\/\{0,1\}raw/|{raw_dir}/|')"
+
   if [ -f "$_pd/plugin.yaml" ]; then
     _keys="$(awk '
       /^config_defaults:[ ]*$/ || /^config_defaults:[ ]*#/ { in_c=1; next }
@@ -140,22 +165,23 @@ plugin_resolve_placeholders() {
           _v="$(normalize_rel_path "$_v")"
           ;;
       esac
-      _res="$(printf '%s' "$_res" | sed -e "s|{$_k}|$_v|g")"
+      [ -n "$_v" ] && _res="$(printf '%s' "$_res" | sed -e "s|{$_k}|$_v|g")"
     done
   fi
 
-  # Fallback resolution for core wiki/raw placeholders and legacy prefixes
+  # Fallback resolution for core wiki/raw placeholders
   _w_val="$(yaml_plugin_get "$_p" "wiki_dir" 2>/dev/null || true)"
   [ -n "$_w_val" ] || _w_val="wiki"
   _w_val="$(normalize_rel_path "$_w_val")"
+  [ -n "$_w_val" ] || _w_val="wiki"
 
   # {raw_dir} (legacy alias) resolves to the first explicit directory source; when no
   # directory source exists it stays unresolved so callers can skip the destination.
   _r_val="$(plugin_primary_source_dir "$_p" 2>/dev/null || true)"
 
-  _res="$(printf '%s' "$_res" | sed -e "s|{wiki_dir}|${_w_val}|g" -e "s|^\.\{0,1\}\/\{0,1\}wiki/|${_w_val}/|")"
+  _res="$(printf '%s' "$_res" | sed -e "s|{wiki_dir}|${_w_val}|g")"
   if [ -n "$_r_val" ]; then
-    _res="$(printf '%s' "$_res" | sed -e "s|{raw_dir}|${_r_val}|g" -e "s|^\.\{0,1\}\/\{0,1\}raw/|${_r_val}/|")"
+    _res="$(printf '%s' "$_res" | sed -e "s|{raw_dir}|${_r_val}|g")"
   fi
 
   _res="$(printf '%s' "$_res" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' | tr -d "'\"" | sed -e 's#^\./##')"
@@ -168,7 +194,8 @@ plugin_instantiate_template() {
 
   _w_val="$(yaml_plugin_get "$_p" "wiki_dir" 2>/dev/null || true)"
   [ -z "$_w_val" ] && _w_val="wiki"
-  _w_val="$(printf '%s' "$_w_val" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' | tr -d "'\"" | sed -e 's#^/##' -e 's#/$##')"
+  _w_val="$(normalize_rel_path "$_w_val")"
+  [ -z "$_w_val" ] && _w_val="wiki"
 
   _r_val="$(plugin_primary_source_dir "$_p" 2>/dev/null || true)"
   [ -z "$_r_val" ] && _r_val="docs"
@@ -214,8 +241,10 @@ sync_plugin_bundle() {
 # Clean up obsolete leaked root ./raw and ./wiki directories if non-default paths are configured
 _clean_leaked_plugin_dirs() {
   _cld_root="${1:-$NEXUS_DIR}"
-  _cld_raw="$2"
-  _cld_wiki="$3"
+  _cld_raw="$(normalize_rel_path "$2")"
+  _cld_wiki="$(normalize_rel_path "$3")"
+  [ -n "$_cld_raw" ] || _cld_raw="docs"
+  [ -n "$_cld_wiki" ] || _cld_wiki="wiki"
 
   if [ "$_cld_raw" != "raw" ] && [ -d "$_cld_root/raw" ] && \
      ! plugin_source_dirs "karpathy-llm" 2>/dev/null | grep -qx 'raw'; then

package/lib/repos.sh

@@ -63,11 +63,6 @@ repo_readonly() {
   yaml_repo_readonly "$1"
 }
 
-# Backwards-compatibility alias for checking if member .rnex exists
-repo_rnex_dir_enabled() {
-  repo_has_rnex_dir "$1"
-}
-
 # Cleanly tear down .rnex in a member repository.
 # Removes auto-generated plugins and boilerplate README, pruning empty directories
 # while preserving any user-customized files.