repo-nexus 0.7.36 → 0.7.39

package/lib/ai.sh

@@ -6,6 +6,10 @@
 
 # ---- 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"
@@ -60,6 +64,8 @@ GI_EOF
 
 # ---- AI Instructions Compilation (.rnex/ai-instructions.md) ----------------
 
+# 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() {
   _dir="${1:-$NEXUS_DIR}"
   _ai_file="$_dir/.rnex/ai-instructions.md"
@@ -97,7 +103,9 @@ Execute in sequence before task execution:
 Autonomous subagents are defined under `.rnex/agents/` and active plugin agents under `.rnex/plugins/<plugin-name>/agents/`.
 
 ## Member Repositories (`repos/<name>/`)
-Each member repository is an autonomous Git repository. For repository-specific instructions, inspect `repos/<name>/.rnex/`. Inspect only targeted files required for the task.
+Each member repository is an autonomous Git repository. Inspect only targeted files required for the task.
+If repository-specific context exists, it is stored under `repos/<name>/.rnex/`.
+Repositories marked `readonly: true` in configuration are reference-only: DO NOT modify, write to, or commit changes in read-only repositories; use them strictly for information, code exploration, and schema references.
 
 ## Workspace Maintenance
 When workspace configuration, routing blocks, plugin assets, or member repository structures require reconciliation or schema upgrades:
@@ -105,7 +113,7 @@ When workspace configuration, routing blocks, plugin assets, or member repositor
 - Use `rnex sync -y` to non-destructively apply configuration version upgrades automatically.
 
 ## Git Operations
-Commit and push changes directly within the respective member repository root (`repos/<name>/`).
+Commit and push changes directly within the respective member repository root (`repos/<name>/`). For read-only repositories (`readonly: true`), never commit, edit, or push changes.
 BASE_AI_EOF
   fi
 
@@ -150,6 +158,8 @@ BASE_AI_EOF
 
 # ---- Multi-Root IDE Workspace (.code-workspace) ----------------------------
 
+# Generate and maintain a multi-root VS Code / Cursor workspace file (.code-workspace).
+# Adds workspace root and each active member repository as first-class workspace folders.
 sync_code_workspace() {
   [ -n "$CODE_WORKSPACE_FILE" ] || return 0
   _ws_path="$NEXUS_DIR/$CODE_WORKSPACE_FILE"
@@ -260,6 +270,7 @@ get_active_provider_skill_dirs() {
           claude)   _sdir=".claude/skills" ;;
           windsurf) _sdir=".windsurf/rules" ;;
           gemini)   _sdir=".agents/skills" ;;
+          codex)    _sdir=".codex/skills" ;;
         esac
       fi
       if [ -n "$_sdir" ]; then
@@ -273,6 +284,8 @@ get_active_provider_skill_dirs() {
   printf '%s' "$_dirs"
 }
 
+# Synchronize built-in core agentic skills into .rnex/skills/ and register
+# zero-logic user skill pointers across all active AI assistant directories.
 sync_rnex_base_assets() {
   _src_toolkit=""
   if [ -d "$SCRIPT_LOCATION/toolkit" ]; then

package/lib/commands/completion.sh

@@ -4,6 +4,10 @@
 # lib/commands/completion.sh — Shell completion generators (bash, zsh, fish)
 # ============================================================================
 
+# Generate tab-completion script for the requested shell (bash, zsh, or fish).
+# Usage:
+#   source <(rnex completion bash)
+#   source <(rnex completion zsh)
 cmd_completion() {
   _shell="${1:-bash}"
   case "$_shell" in
@@ -14,7 +18,7 @@ _rnex_completions() {
   COMPREPLY=()
   cur="${COMP_WORDS[COMP_CWORD]}"
   prev="${COMP_WORDS[COMP_CWORD-1]}"
-  commands="init install add clone exec remove enable disable list sync status rnex-dir update upgrade hooks plugin completion version help"
+  commands="init install add clone exec remove enable disable readonly list sync status rnex-dir update upgrade hooks plugin completion version help"
 
   case "$prev" in
     rnex)
@@ -37,7 +41,7 @@ _rnex_completions() {
       COMPREPLY=( $(compgen -W "install uninstall status" -- "$cur") )
       return 0
       ;;
-    enable|disable|remove|show|hide|rnex-dir)
+    enable|disable|readonly|remove|show|hide|rnex-dir)
       local repos
       repos=$(rnex list 2>/dev/null | awk 'NR>2 {print $1}')
       COMPREPLY=( $(compgen -W "$repos" -- "$cur") )
@@ -81,6 +85,7 @@ _rnex() {
     'remove:Unregister and delete a repository'
     'enable:Enable a repository in active workspace'
     'disable:Disable a repository in workspace'
+    'readonly:Toggle read-only (information-only) status for a repo'
     'list:List member repositories'
     'sync:Reconcile workspace, plugins, skills, and member .rnex directories'
     'status:Inspect workspace health and status (read-only)'
@@ -124,7 +129,7 @@ _rnex() {
           hook_cmds=('install:Install Git hooks' 'uninstall:Uninstall Git hooks' 'status:Show Git hooks status')
           _describe -t hook_cmds 'hooks command' hook_cmds
           ;;
-        enable|disable|remove|show|hide|rnex-dir)
+        enable|disable|readonly|remove|show|hide|rnex-dir)
           local -a repos
           repos=($(rnex list 2>/dev/null | awk 'NR>2 {print $1}'))
           _describe -t repos 'repository' repos
@@ -163,6 +168,9 @@ complete -c rnex -n "__fish_use_subcommand" -a exec -d "Execute command across m
 complete -c rnex -n "__fish_use_subcommand" -a remove -d "Remove a repository"
 complete -c rnex -n "__fish_use_subcommand" -a enable -d "Enable a repository"
 complete -c rnex -n "__fish_use_subcommand" -a disable -d "Disable a repository"
+complete -c rnex -n "__fish_use_subcommand" -a readonly -d "Toggle read-only status for a repo"
+complete -c rnex -n "__fish_seen_subcommand_from readonly" -a "enable disable"
+complete -c rnex -n "__fish_seen_subcommand_from readonly" -l local -d "Apply locally"
 complete -c rnex -n "__fish_use_subcommand" -a list -d "List repositories"
 complete -c rnex -n "__fish_use_subcommand" -a rnex-dir -d "Toggle .rnex directory integration for a repo"
 complete -c rnex -n "__fish_seen_subcommand_from rnex-dir" -a "enable disable"

package/lib/commands/init.sh

@@ -4,6 +4,11 @@
 # lib/commands/init.sh — Workspace initialization command
 # ============================================================================
 
+# Initialize a new Repo Nexus workspace in the specified directory (or current directory):
+# Sets up rnex.yaml, .rnex/ harness, gitignore rules, routing instructions in AGENTS.md,
+# enabled plugins (e.g. --claude, --gemini, --karpathy), and optional VS Code / Cursor workspace.
+# Usage:
+#   rnex init [-y|--yes] [--hooks|--no-hooks] [--<plugin>] [<directory>]
 cmd_init() {
   _non_interactive=0
   _init_dir=""
@@ -165,7 +170,7 @@ YAML_EOF
   if ! has_active_provider_instructions "$_init_dir"; then
     merge_rnex_instructions "$_init_dir/AGENTS.md"
   fi
-  for _if in CLAUDE.md GEMINI.md .cursorrules .windsurfrules .github/copilot-instructions.md; do
+  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
 
@@ -216,7 +221,7 @@ YAML_EOF
     log_dim "Created $_created_items"
     printf '\n'
     log_info "Next steps:"
-    log_dim "1. Add repositories with: rnex add <name> <git-url>"
+    log_dim "1. Add repositories with: rnex add [<name>] <git-url>"
     log_dim "2. Clone team repositories: rnex clone"
     log_dim "3. Run commands across all repos: rnex exec <command>"
   fi

package/lib/commands/plugin.sh

@@ -4,6 +4,7 @@
 # lib/commands/plugin.sh — Plugin management commands
 # ============================================================================
 
+# List all available, enabled, and disabled plugins found in the workspace toolkit.
 cmd_plugin_list() {
   require_workspace
   printf '\n%b%s%b\n' "$_B" "Repo Nexus Plugins" "$_NC"
@@ -35,6 +36,7 @@ cmd_plugin_list() {
   printf '\n'
 }
 
+# Display detailed metadata, configurable options, and template paths for a specific plugin.
 cmd_plugin_info() {
   require_workspace
   _pname="$1"
@@ -73,6 +75,7 @@ cmd_plugin_info() {
     gemini)   _skill_target=".agents/skills/" ;;
     cursor)   _skill_target=".cursor/rules/" ;;
     windsurf) _skill_target=".windsurf/rules/" ;;
+    codex)    _skill_target=".codex/skills/" ;;
   esac
   case "$_skill_target" in
     */|"") ;;
@@ -144,6 +147,7 @@ cmd_plugin_info() {
   printf '\n'
 }
 
+# Enable a plugin in workspace configuration (team or local) and sync assets.
 cmd_plugin_enable() {
   require_workspace
   _is_local=0
@@ -176,6 +180,7 @@ cmd_plugin_enable() {
   log_ok "Plugin '$_name' active in workspace (.rnex/plugins/$_name)"
 }
 
+# Disable a plugin, dispatch before_plugin_disable hook, and prune its assets.
 cmd_plugin_disable() {
   require_workspace
   _is_local=0
@@ -215,6 +220,9 @@ cmd_plugin_disable() {
   cmd_sync -q
 }
 
+# Toggle the member repository .rnex harness (enable or disable) for a specific repo.
+# Usage:
+#   rnex rnex-dir <enable|disable> <name> [--local]
 cmd_rnex_dir() {
   require_workspace
   _action=""

package/lib/commands/repo.sh

@@ -4,25 +4,31 @@
 # lib/commands/repo.sh — Member repository management commands
 # ============================================================================
 
+# Register a new repository in workspace configuration and clone it into ./repos/<name>.
+# Usage:
+#   rnex add [--local] [--disabled] [--readonly] [<name>] <git-url>
+# If <name> is omitted, it is inferred from the last component of <git-url>.
 cmd_add() {
   require_workspace
-  _name=""
-  _url=""
-  _rnex_dir="true"
+  _arg1=""
+  _arg2=""
   _enabled="true"
+  _readonly="false"
   _is_local=0
 
   while [ $# -gt 0 ]; do
     case "$1" in
       --local) _is_local=1 ;;
       --disabled) _enabled="false" ;;
-      --no-rnex-dir|--rnex-dir=false) _rnex_dir="false" ;;
-      --rnex-dir|--rnex-dir=true)    _rnex_dir="true" ;;
+      --readonly) _readonly="true" ;;
+      --no-rnex-dir|--rnex-dir=false|--rnex-dir|--rnex-dir=true)
+        # Obsolete flag ignored after transition to on-demand member .rnex
+        ;;
       *)
-        if [ -z "$_name" ]; then
-          _name="$1"
-        elif [ -z "$_url" ]; then
-          _url="$1"
+        if [ -z "$_arg1" ]; then
+          _arg1="$1"
+        elif [ -z "$_arg2" ]; then
+          _arg2="$1"
         else
           die "Unexpected argument: $1"
         fi
@@ -31,8 +37,21 @@ cmd_add() {
     shift
   done
 
-  [ -n "$_name" ] || die "Usage: rnex add [--local] [--disabled] [--no-rnex-dir] <name> <git-url>"
-  [ -n "$_url" ] || die "Usage: rnex add [--local] [--disabled] [--no-rnex-dir] <name> <git-url>"
+  # Derive repo name and URL:
+  # - If 2 positional args: <name> <git-url>
+  # - If 1 positional arg:  <git-url> (name inferred from the last component of the path/URL)
+  if [ -n "$_arg2" ]; then
+    _name="$_arg1"
+    _url="$_arg2"
+  elif [ -n "$_arg1" ]; then
+    _url="$_arg1"
+    _name="$(repo_name_from_path "$_url")"
+  else
+    die "Usage: rnex add [--local] [--disabled] [--readonly] [<name>] <git-url>"
+  fi
+
+  [ -n "$_name" ] || die "Could not determine repository name from '$_url'"
+  [ -n "$_url" ] || die "Usage: rnex add [--local] [--disabled] [--readonly] [<name>] <git-url>"
 
   ensure_repos_dir
   _target_dir="$(resolve_repo_path "$_name")"
@@ -47,7 +66,7 @@ cmd_add() {
 
   if [ "$_is_local" -eq 1 ]; then
     yaml_set_local "$_name" "url" "$_url"
-    [ "$_rnex_dir" = "false" ] && yaml_set_local "$_name" "rnex_dir" "false"
+    [ "$_readonly" = "true" ] && yaml_set_local "$_name" "readonly" "true"
     [ "$_enabled" = "false" ] && yaml_set_local "$_name" "enabled" "false"
     sync_repo_rnex "$_name"
     sync_code_workspace
@@ -64,7 +83,7 @@ cmd_add() {
       die "Repo '$_name' is already registered in $(basename "$WORKSPACE_YAML")"
     else
       yaml_set "$_name" "url" "$_url"
-      [ "$_rnex_dir" = "false" ] && yaml_set "$_name" "rnex_dir" "false"
+      [ "$_readonly" = "true" ] && yaml_set "$_name" "readonly" "true"
       [ "$_enabled" = "false" ] && yaml_set "$_name" "enabled" "false"
       sync_repo_rnex "$_name"
       sync_code_workspace
@@ -75,7 +94,7 @@ cmd_add() {
     fi
   fi
 
-  yaml_add_repo "$_name" "$_url" "$_rnex_dir" "$_enabled"
+  yaml_add_repo "$_name" "$_url" "$_enabled" "$_readonly"
   sync_repo_rnex "$_name"
   sync_code_workspace
   run_hook "after_sync" "$@"
@@ -83,6 +102,8 @@ cmd_add() {
   log_ok "Registered and added repo '${_name}'"
 }
 
+# Clone all enabled repositories declared in configuration that are not yet cloned.
+# Skips disabled repositories and already existing clones.
 cmd_clone() {
   require_workspace
   ensure_repos_dir
@@ -127,6 +148,8 @@ cmd_clone() {
   printf '\n'
 }
 
+# Execute a shell command across all enabled member repositories in ./repos/<name>.
+# Propagates non-zero exit codes if any repository command fails.
 cmd_exec() {
   require_workspace
   [ $# -gt 0 ] || die "Usage: rnex exec <command...>"
@@ -198,6 +221,7 @@ _repo_toggle_state() {
   _repo_set_config_and_log "$_name" "enabled" "$_target_val" "$_is_local" "$_verb"
 }
 
+# Enable a member repository in configuration and reconcile its workspace state.
 cmd_enable() {
   _repo_toggle_state "true" "Enabled repo" "$@"
   sync_repo_rnex "$_name"
@@ -205,6 +229,7 @@ cmd_enable() {
   run_hook "after_sync" "$@"
 }
 
+# Disable a member repository in configuration (skips execution and hides from IDE).
 cmd_disable() {
   _repo_toggle_state "false" "Disabled repo" "$@"
   sync_code_workspace
@@ -218,6 +243,57 @@ cmd_hide() {
   cmd_disable "$@"
 }
 
+# Toggle the member repository read-only setting (enable or disable) for a specific repo.
+# When a repository is read-only, it is strictly used for information / reference.
+# Usage:
+#   rnex readonly <enable|disable> <name> [--local]
+cmd_readonly() {
+  require_workspace
+  _action=""
+  _name=""
+  _is_local=0
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --local) _is_local=1 ;;
+      enable|true|yes|1)
+        if [ -z "$_action" ]; then _action="true"; else _name="$1"; fi
+        ;;
+      disable|false|no|0)
+        if [ -z "$_action" ]; then _action="false"; else _name="$1"; fi
+        ;;
+      *)
+        if [ -z "$_action" ] && [ "$1" = "enable" ] || [ "$1" = "disable" ]; then
+          _action="$1"
+        elif [ -z "$_name" ]; then
+          _name="$1"
+        elif [ -z "$_action" ]; then
+          _action="$1"
+        fi
+        ;;
+    esac
+    shift
+  done
+
+  case "$_action" in
+    enable|true|yes|1) _action="true" ;;
+    disable|false|no|0) _action="false" ;;
+    "") _action="true" ;;
+  esac
+
+  [ -n "$_name" ] || die "Usage: rnex readonly <enable|disable> <name> [--local]"
+  yaml_has_repo "$_name" || die "Repo '$_name' is not registered"
+
+  if [ "$_action" = "true" ]; then
+    _repo_set_config_and_log "$_name" "readonly" "true" "$_is_local" "Marked repo as read-only"
+  else
+    _repo_set_config_and_log "$_name" "readonly" "false" "$_is_local" "Disabled read-only mode for"
+  fi
+  sync_code_workspace
+  run_hook "after_sync" "$@"
+}
+
+# Remove a member repository from configuration and delete its local directory in ./repos/<name>.
 cmd_remove() {
   require_workspace
   _name=""
@@ -251,9 +327,11 @@ cmd_remove() {
   run_hook "after_sync" "$@"
 }
 
+# Print a tabular status list of all registered member repositories, showing
+# state (enabled/disabled), clone status, active git branch, readonly status, and URL.
 cmd_list() {
   require_workspace
-  printf '\n%b%-18s %-10s %-8s %-14s %-10s %s%b\n' "$_B" "NAME" "STATE" "CLONED" "BRANCH" "RNEX_DIR" "URL" "$_NC"
+  printf '\n%b%-18s %-10s %-8s %-14s %-10s %s%b\n' "$_B" "NAME" "STATE" "CLONED" "BRANCH" "READONLY" "URL" "$_NC"
   printf '%-18s %-10s %-8s %-14s %-10s %s\n' "----" "-----" "------" "------" "--------" "---"
   yaml_list_repos | while read -r _name; do
     [ -n "$_name" ] || continue
@@ -275,13 +353,13 @@ cmd_list() {
       [ -n "$_b" ] && _branch="$_b"
     fi
 
-    _rd="true"
-    if ! repo_rnex_dir_enabled "$_name"; then
-      _rd="false"
+    _ro="false"
+    if yaml_repo_readonly "$_name"; then
+      _ro="${_Y}true${_NC}"
     fi
 
-    printf '%-18s %-19b %-17b %-14s %-10s %s\n' \
-      "$_name" "$_state" "$_cloned" "$_branch" "$_rd" "${_url:-(none)}"
+    printf '%-18s %-19b %-17b %-14s %-19b %s\n' \
+      "$_name" "$_state" "$_cloned" "$_branch" "$_ro" "${_url:-(none)}"
   done
   printf '\n'
 }

package/lib/commands/status.sh

@@ -4,6 +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
@@ -17,10 +18,14 @@ _status_active_plugin_trigger() {
   return 0
 }
 
+# Check if a directory contains any rnex-* user skills or skill symlinks.
 _status_has_rnex_skills() {
   [ -d "$1" ] && { ls "$1"/rnex-*.md >/dev/null 2>&1 || ls -d "$1"/rnex-* >/dev/null 2>&1; }
 }
 
+# Print comprehensive read-only workspace diagnostic report:
+# Shows config versions, gitignore rules, AI context routing, registered plugins,
+# git hooks status, and member repository status.
 cmd_status() {
   require_workspace
   ensure_repos_dir
@@ -146,6 +151,7 @@ cmd_status() {
   for _pair in \
     "CLAUDE.md:Claude" \
     "GEMINI.md:Gemini" \
+    "CODEX.md:Codex" \
     ".cursorrules:Cursor" \
     ".windsurfrules:Windsurf" \
     ".github/copilot-instructions.md:Copilot"; do
@@ -179,6 +185,7 @@ cmd_status() {
     ".windsurf/rules/:Windsurf" \
     ".agents/skills/:Gemini" \
     ".gemini/skills/:Gemini" \
+    ".codex/skills/:Codex" \
     ".github/skills/:Copilot"; do
     _sdir="${_spair%%:*}"
     _slbl="${_spair#*:}"
@@ -235,7 +242,7 @@ cmd_status() {
   printf '%b%s%b\n' "$_BOLD" "Member Repositories:" "$_NC"
   _all_repos="$(yaml_list_repos)"
   if [ -z "$_all_repos" ]; then
-    printf '  %b%s%b\n' "$_DIM" "(No repositories registered yet. Use 'rnex add <name> <git-url>')" "$_NC"
+    printf '  %b%s%b\n' "$_DIM" "(No repositories registered yet. Use 'rnex add [<name>] <git-url>')" "$_NC"
   else
     echo "$_all_repos" | while read -r _name; do
       [ -n "$_name" ] || continue
@@ -247,17 +254,14 @@ cmd_status() {
         printf '  %b○%b %-18s %b[disabled]%b %s\n' "$_DIM" "$_NC" "$_name" "$_DIM" "$_NC" "${_url:+- $_url}"
       elif [ -d "$_rdir/.git" ]; then
         _b="$(git -C "$_rdir" symbolic-ref --short HEAD 2>/dev/null || git -C "$_rdir" rev-parse --short HEAD 2>/dev/null || echo "head")"
-        _rnex_tag=""
-        if repo_rnex_dir_enabled "$_name"; then
-          if [ -d "$_rdir/.rnex" ]; then
-            _rnex_tag=" ${_DIM}[.rnex ✓]${_NC}"
-          else
-            _rnex_tag=" ${_Y}[.rnex pending]${_NC}"
-          fi
-        else
-          _rnex_tag=" ${_DIM}[.rnex off]${_NC}"
+        _tags=""
+        if yaml_repo_readonly "$_name"; then
+          _tags=" ${_Y}[readonly]${_NC}"
+        fi
+        if [ -d "$_rdir/.rnex" ]; then
+          _tags="${_tags} ${_DIM}[.rnex]${_NC}"
         fi
-        printf '  %b●%b %-18s %b[%s]%b%b %s\n' "$_G" "$_NC" "$_name" "$_C" "$_b" "$_NC" "$_rnex_tag" "${_url:+- $_url}"
+        printf '  %b●%b %-18s %b[%s]%b%b %s\n' "$_G" "$_NC" "$_name" "$_C" "$_b" "$_NC" "$_tags" "${_url:+- $_url}"
       else
         printf '  %b✗%b %-18s %b[missing — run "rnex clone"]%b %s\n' "$_R" "$_NC" "$_name" "$_R" "$_NC" "${_url:+- $_url}"
       fi

package/lib/commands/sync.sh

@@ -4,6 +4,8 @@
 # lib/commands/sync.sh — Workspace reconciliation and compilation
 # ============================================================================
 
+# Write the standalone .rnex/bin/auto-sync.sh helper used by hooks and subshells
+# to rapidly verify workspace stamp checksum and trigger rnex sync on config changes.
 _write_auto_sync_script() {
   _dir="${1:-$NEXUS_DIR}"
   _bin_dir="$_dir/.rnex/bin"
@@ -31,6 +33,12 @@ EOF
   chmod +x "$_script"
 }
 
+# Primary workspace reconciliation command:
+# Reconciles workspace configuration version, .gitignore / .ignore routing, AGENTS.md,
+# core skills, AI instruction compilation, active plugins, Git hooks, member .rnex
+# harnesses, and VS Code / Cursor workspace files.
+# Usage:
+#   rnex sync [-y|--yes] [-q|--quiet] [--upgrade]
 cmd_sync() {
   require_workspace
   ensure_repos_dir

package/lib/commands/system.sh

@@ -4,18 +4,47 @@
 # lib/commands/system.sh — System commands: install, version, help
 # ============================================================================
 
+# Install rnex and repo-nexus executables and asset libraries into user bin and share directories.
 cmd_install() {
-  _target_bin="${1:-$HOME/.local/bin}"
+  _target_bin="${1:-${RNEX_BIN_DIR:-$HOME/.local/bin}}"
   _target_bin="$(resolve_path "$_target_bin")"
   mkdir -p "$_target_bin"
 
-  _source_cli="$SCRIPT_LOCATION/rnex"
-  [ -f "$_source_cli" ] || _source_cli="$SCRIPT_LOCATION"
+  _src_root="$SCRIPT_LOCATION"
+  [ -f "$_src_root/rnex" ] || _src_root="$(dirname "$SCRIPT_LOCATION")"
+  _source_cli="$_src_root/rnex"
   [ -f "$_source_cli" ] || die "Could not locate source CLI executable to install"
 
-  chmod +x "$_source_cli"
-  ln -sf "$_source_cli" "$_target_bin/rnex"
-  ln -sf "$_source_cli" "$_target_bin/repo-nexus"
+  if [ -n "${RNEX_INSTALL_DIR:-}" ]; then
+    _install_dir="$(resolve_path "$RNEX_INSTALL_DIR")"
+  elif [ -n "${1:-}" ]; then
+    case "$(basename "$_target_bin")" in
+      bin) _install_dir="$(dirname "$_target_bin")/share/repo-nexus" ;;
+      *)   _install_dir="$_target_bin" ;;
+    esac
+  else
+    _install_dir="$HOME/.local/share/repo-nexus"
+  fi
+
+  mkdir -p "$_install_dir"
+  if [ "$_src_root" != "$_install_dir" ]; then
+    rm -rf "$_install_dir/docs"
+    cp "$_source_cli" "$_install_dir/rnex"
+    [ -f "$_src_root/package.json" ] && cp "$_src_root/package.json" "$_install_dir/package.json"
+    for _asset in lib templates toolkit; do
+      if [ -d "$_src_root/$_asset" ]; then
+        rm -rf "${_install_dir:?}/$_asset"
+        cp -R "$_src_root/$_asset" "$_install_dir/$_asset"
+      fi
+    done
+  fi
+
+  _installed_cli="$_install_dir/rnex"
+  chmod +x "$_installed_cli"
+  if [ "$_target_bin" != "$_install_dir" ]; then
+    ln -sf "$_installed_cli" "$_target_bin/rnex"
+  fi
+  ln -sf "$_installed_cli" "$_target_bin/repo-nexus"
 
   log_ok "Installed 'rnex' and 'repo-nexus' into $_target_bin"
   case ":$PATH:" in
@@ -28,10 +57,12 @@ cmd_install() {
   esac
 }
 
+# Output current Repo Nexus version from package.json.
 cmd_version() {
   printf 'rnex %s\n' "$RNEX_VERSION"
 }
 
+# Check workspace configuration version against current CLI and run sync to upgrade if needed.
 cmd_update() {
   require_workspace
   _cmp=0
@@ -48,6 +79,7 @@ cmd_upgrade() {
   cmd_update "$@"
 }
 
+# Display complete CLI usage, command catalog, options, and practical examples.
 cmd_help() {
   cat <<EOF
 
@@ -63,7 +95,7 @@ cmd_help() {
     -v, --version           Show version
 
   WORKSPACE & SYSTEM SETUP
-    init [-y] [--code-workspace [file]] [--hooks|--no-hooks] [--copilot] [--claude] [--gemini] [--cursor] [--windsurf] [--karpathy] [dir]
+    init [-y] [--code-workspace [file]] [--hooks|--no-hooks] [--copilot] [--claude] [--gemini] [--codex] [--cursor] [--windsurf] [--karpathy] [dir]
                             Initialize a new Repo Nexus workspace (default: AGENTS.md)
     install [dir]           Install rnex & repo-nexus globally into ~/.local/bin (or custom dir)
     sync [-y] [--quiet]     Reconcile workspace, plugins, skills, member .rnex directories, and compile AI instructions
@@ -75,15 +107,16 @@ cmd_help() {
     completion <shell>      Generate shell completion script (bash, zsh, fish)
 
   REPO MANAGEMENT
-    add [--local] [--disabled] [--no-rnex-dir] <name> <git-url>
+    add [--local] [--disabled] [--readonly] [<name>] <git-url>
                             Register and clone repo (--local writes to .local.rnex.yaml)
     clone                   Clone all missing enabled repositories declared in rnex.yaml
     exec <command...>       Execute a shell command across all active member repositories
     remove <name>           Unregister and delete member repository
     enable [--local] <name> Enable a member repository in active workspace
     disable [--local] <name> Disable a member repository in workspace
+    readonly [--local] <enable|disable> <name>
+                            Toggle read-only (information-only) status for a member repo
     list                    List all member repositories with clone state & active branch
-    rnex-dir <enable|disable> <name>  Toggle .rnex directory integration for a member repo
 
   PLUGIN MANAGEMENT
     plugin [list]           List available and enabled plugins