repo-nexus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Repo Nexus Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# Repo Nexus (`rnex`)
+
+[![CI](https://github.com/nu-nenoi/repo-nexus/actions/workflows/ci.yml/badge.svg)](https://github.com/nu-nenoi/repo-nexus/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/repo-nexus.svg)](https://www.npmjs.com/package/repo-nexus)
+[![License: MIT](https://img.shields.io/github/license/nu-nenoi/repo-nexus)](LICENSE)
+[![POSIX Compatible](https://img.shields.io/badge/POSIX-compatible-success)](#)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-lightgrey)](#)
+
+A tooling-independent, zero-dependency workspace orchestrator for multiple repositories with shared, auto-synced AI context across projects using Unix symlinks.
+
+- **No git submodules, subtrees, or nested git friction**
+- **No IDE lock-in** (works across VS Code, Cursor, Antigravity, Claude Code, Zed, terminal agents)
+- **AI provider-agnostic** (shares `AGENTS.md`, Copilot instructions, Cursor rules, and custom prompts)
+- **Automatic AI context injection** on repository registration
+- **Auto-detects existing AI configs** (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, Copilot instructions, etc.)
+- **Context-aware**: Finds and uses `rnex.yaml` automatically from your current directory or parent tree
+- **Zero dependencies** (pure POSIX shell CLI)
+
+---
+
+## How It Works: The Two Symlink Flows
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. SCOPE IN — Bring member repos INTO Repo Nexus           │
+│                                                             │
+│  my-workspace/                                              │
+│    repos/                                                   │
+│      backend/   ──(symlink)──>  ~/code/backend-api          │
+│      frontend/  ──(symlink)──>  ~/code/web-app              │
+│    AGENTS.md         (universal AI instructions)            │
+│    rnex.yaml         (manifest: AI files + repos)           │
+│                                                             │
+│  Agent opens workspace → sees all repos in one place.       │
+│  Edits through symlinks modify the original files directly. │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│  2. INJECT OUT — Auto-sync AI context INTO member repos     │
+│                                                             │
+│  ~/code/backend-api/                                        │
+│    AGENTS.md     ──(symlink)──>  my-workspace/AGENTS.md     │
+│    src/              (real codebase)                        │
+│                                                             │
+│  Open backend-api standalone → AI tools automatically see   │
+│  shared instructions as if they were local files.           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Principles
+
+1. **Symlink Write-Through**:
+   Symlinks are transparent pointers. When an AI agent or developer edits `repos/backend/src/index.ts`, the OS resolves the link and writes directly to the source repository on disk.
+
+2. **Autonomous Git Repositories**:
+   Each member repository retains its own Git history, branches, and remotes. Git operations (commit, push, pull) are executed directly inside each member repo.
+
+3. **Single Source of Truth for AI Context**:
+   Edit `AGENTS.md` in Repo Nexus, and changes immediately reflect across all member repositories.
+
+4. **Dynamic Workspace Scope**:
+   Easily show or hide member repos from the active workspace without modifying disk contents.
+
+---
+
+## Installation
+
+You can install `rnex` using either the native zero-dependency installer or via npm:
+
+### Option 1: Native Installer (Zero Dependencies)
+
+Clone the repository and run the built-in installer:
+
+```bash
+git clone https://github.com/nu-nenoi/repo-nexus.git
+cd repo-nexus
+./rnex install
+```
+*(Installs `rnex` and `repo-nexus` symlinks into `~/.local/bin`, or pass a custom directory like `./rnex install /usr/local/bin`)*
+
+### Option 2: Via npm
+
+```bash
+npm install -g repo-nexus
+```
+*(Installs both `repo-nexus` and `rnex` executable commands globally)*
+
+### Option 3: Shell Alias
+
+Add to your `~/.zshrc` or `~/.bashrc`:
+```bash
+alias rnex="/path/to/repo-nexus/rnex"
+alias repo-nexus="/path/to/repo-nexus/rnex"
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialize a new workspace
+mkdir my-workspace && cd my-workspace
+rnex init
+
+# 2. Register repositories
+rnex add backend ~/code/backend-api
+rnex add frontend ../web-app          # relative paths work too
+
+# 3. Check workspace health
+rnex status
+```
+
+During `rnex init`, the CLI automatically scans for existing AI configuration files (like `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`) and adds them to your config.
+
+---
+
+## Everyday Usage
+
+```bash
+# Register a repository (links into scope & auto-injects AI context)
+rnex add my-app ~/code/my-app
+
+# Inspect workspace status & linked AI files
+rnex status
+
+# List all registered repositories
+rnex list
+
+# Temporarily hide a repo from active indexing/agent scope
+rnex hide my-app
+
+# Restore a hidden repo back to active scope
+rnex show my-app
+
+# Reconcile/repair all symlinks across all repos (idempotent)
+rnex sync
+
+# Unregister a repository (removes scope link & cleans up injected AI files)
+rnex remove my-app
+```
+
+---
+
+## Workspace Configuration (`rnex.yaml`)
+
+The configuration file defines repo symlink directory, AI context files to sync, and registered repositories:
+
+```yaml
+# Directory for repository symlinks (relative or absolute)
+repos_dir: ./repos
+
+# AI context files to automatically sync into every member repo
+ai_files:
+  - AGENTS.md
+  - .github/copilot-instructions.md
+  # - .cursorrules
+  # - CLAUDE.md
+
+# Member repositories
+repos:
+  backend:
+    path: /Users/dev/code/backend-api
+    scope: visible
+  frontend:
+    path: ../web-app
+    scope: visible
+  analytics:
+    path: /Users/dev/code/analytics
+    scope: hidden
+```
+
+> See [`docs/rnex.example.yaml`](docs/rnex.example.yaml) for a comprehensive example with all options and supported AI tool configs.
+
+---
+
+## CLI Command Reference
+
+### Global Options
+| Option | Description |
+|:---|:---|
+| `-c, --config <file>` | Explicit path to `rnex.yaml` (executes in that workspace directory) |
+| `-h, --help` | Display command help and usage instructions |
+| `-v, --version` | Display version |
+
+### Commands
+| Command | Description |
+|:---|:---|
+| `rnex init [dir]` | Initialize a new workspace in current (or target) directory |
+| `rnex install [dir]` | Install `rnex` & `repo-nexus` globally into `~/.local/bin` (or custom dir) |
+| `rnex add <name> <path>` | Register repo, create scope symlink, and auto-inject AI context |
+| `rnex remove <name>` | Unregister repo, unlink from scope, and clean up injected AI files |
+| `rnex list` | List all registered repos and visibility scopes |
+| `rnex status` | Display status of AI context files, active member repos, and paths |
+| `rnex show <name>` | Make a hidden repo visible in workspace |
+| `rnex hide <name>` | Hide a repo from active workspace indexing |
+| `rnex sync` | Reconcile all scope symlinks and AI context files from config |
+
+---
+
+## Operating on External Workspaces via `--config`
+
+Run `rnex` commands targeting any workspace without changing directories:
+
+```bash
+# Inspect status of a workspace stored elsewhere
+rnex -c /path/to/my-workspace/rnex.yaml status
+
+# Add a repository to an external workspace
+rnex --config /path/to/my-workspace/rnex.yaml add api-service ~/code/api
+```
+
+Any command executed with an explicit config file operates within the directory where that config lives.
+
+---
+
+## Supported AI Configuration Files
+
+`rnex init` auto-detects these files and includes them in your workspace config:
+
+| File / Directory | AI Tool |
+|:---|:---|
+| `AGENTS.md` | Universal AI agent instructions |
+| `CLAUDE.md` | Claude Code |
+| `.cursorrules` | Cursor |
+| `.cursor/rules/` | Cursor (directory) |
+| `.windsurfrules` | Windsurf / Codeium |
+| `.windsurf/rules/` | Windsurf (directory) |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `.aider.conf.yml` | Aider |
+| `CONVENTIONS.md` | Coding conventions |
+| `.clinerules` | Cline / Roo Code |
+| `CODEX.md` | Codex |
+| `.continue/` | Continue.dev |
+| `SKILL.md` | Skills (emerging standard) |
+
+---
+
+## Project Structure
+
+```
+repo-nexus/
+├── rnex.yaml                       # Workspace configuration
+├── rnex                            # CLI executable (POSIX shell)
+├── AGENTS.md                       # Universal AI coding guidelines
+├── docs/
+│   ├── AGENTS.sample.md            # Template for AGENTS.md
+│   └── rnex.example.yaml           # Full config reference with examples
+├── .github/
+│   ├── workflows/ci.yml            # GitHub Actions CI workflow
+│   └── ISSUE_TEMPLATE/             # Bug report and feature request templates
+├── tests/
+│   └── test_cli.sh                 # Automated CLI test suite (11 tests)
+├── toolkit/                        # Shared prompts, scripts, templates
+├── package.json                    # npm package manifest
+├── LICENSE                         # MIT License
+└── README.md
+```
+
+---
+
+## Running Tests
+
+```bash
+./tests/test_cli.sh
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/docs/AGENTS.sample.md

@@ -0,0 +1,10 @@
+# Multi-Repo AI Workspace Context
+
+This workspace operates as a **Repo Nexus** linking multiple independent repositories via symlinks.
+
+## Rules for AI Coding Assistants
+
+1. **Symlink Write-Through**: Files edited under `repos/<name>/` directly modify the target repository.
+2. **Repo Boundaries**: Each repository is isolated. Do not introduce cross-repo imports unless explicitly architected.
+3. **Shared Context**: This file is symlinked across member repositories. Keep instructions universal. Use local instructions for repo-specific rules.
+4. **Git Operations**: Commit and push changes directly within the respective member repository root.

package/docs/rnex.example.yaml

@@ -0,0 +1,90 @@
+# ==============================================================================
+# rnex.yaml — Repo Nexus Workspace Configuration (Full Example)
+# ==============================================================================
+# This file is the central manifest for a Repo Nexus workspace.
+# Place it in your workspace root directory and run `rnex sync` to apply.
+#
+# For more information: https://github.com/nu-nenoi/repo-nexus
+
+# ------------------------------------------------------------------------------
+# repos_dir — Directory for repository symlinks
+# ------------------------------------------------------------------------------
+# Relative paths are resolved relative to this config file's location.
+# Default: ./repos
+#
+# Examples:
+#   repos_dir: ./repos              # relative (recommended)
+#   repos_dir: ./workspace/repos    # nested relative path
+#   repos_dir: /opt/dev/repos       # absolute path
+
+repos_dir: ./repos
+
+# ------------------------------------------------------------------------------
+# ai_files — AI context files to auto-sync into member repositories
+# ------------------------------------------------------------------------------
+# Each file listed here is symlinked from the workspace root into every
+# registered member repository. This keeps AI instructions consistent
+# across all your projects.
+#
+# Paths are relative to the workspace root (where this config file lives).
+# Both files and directories are supported.
+#
+# Well-known AI configuration files by tool:
+#   AGENTS.md                         — Universal AI agent instructions
+#   CLAUDE.md                         — Claude Code project instructions
+#   .cursorrules                      — Cursor editor rules
+#   .cursor/rules/                    — Cursor rules directory
+#   .windsurfrules                    — Windsurf / Codeium rules
+#   .windsurf/rules/                  — Windsurf rules directory
+#   .github/copilot-instructions.md   — GitHub Copilot custom instructions
+#   .aider.conf.yml                   — Aider configuration
+#   CONVENTIONS.md                    — Coding conventions (Aider / general)
+#   .clinerules                       — Cline / Roo Code rules
+#   CODEX.md                          — Codex project instructions
+#   .continue/                        — Continue.dev configuration directory
+#   SKILL.md                          — Skills definition (emerging standard)
+
+ai_files:
+  - AGENTS.md
+  - .github/copilot-instructions.md
+  # - .cursorrules
+  # - CLAUDE.md
+  # - .windsurfrules
+  # - CONVENTIONS.md
+  # - toolkit/prompts/review-checklist.md
+
+# ------------------------------------------------------------------------------
+# repos — Member repositories managed by Repo Nexus
+# ------------------------------------------------------------------------------
+# Each repo has:
+#   path:   Absolute or relative path to the repository on disk.
+#           Relative paths are resolved relative to this config file.
+#   scope:  "visible" (default) creates a symlink in repos_dir.
+#           "hidden" removes the symlink but keeps the registration.
+#
+# Examples with absolute paths:
+#   backend-api:
+#     path: /Users/dev/projects/backend-api
+#     scope: visible
+#
+# Examples with relative paths:
+#   frontend:
+#     path: ../frontend-app
+#     scope: visible
+#
+#   shared-lib:
+#     path: ../../libs/shared
+#     scope: hidden
+
+repos:
+  # backend-api:
+  #   path: /Users/dev/projects/backend-api
+  #   scope: visible
+  #
+  # frontend-app:
+  #   path: ../frontend-app
+  #   scope: visible
+  #
+  # analytics:
+  #   path: /Users/dev/projects/analytics-service
+  #   scope: hidden

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "repo-nexus",
+  "version": "0.1.0",
+  "description": "Tooling-independent multi-repo workspace manager with auto-synced AI context via symlinks",
+  "bin": {
+    "repo-nexus": "./rnex",
+    "rnex": "./rnex"
+  },
+  "files": [
+    "rnex",
+    "README.md",
+    "LICENSE",
+    "docs/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nu-nenoi/repo-nexus.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nu-nenoi/repo-nexus/issues"
+  },
+  "homepage": "https://github.com/nu-nenoi/repo-nexus#readme",
+  "keywords": [
+    "repo",
+    "repository",
+    "workspace",
+    "multi-repo",
+    "monorepo",
+    "symlink",
+    "ai-context",
+    "cli",
+    "agents",
+    "copilot",
+    "cursor",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "author": "Anton Shramkov",
+  "engines": {
+    "node": ">=14"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ]
+}

package/rnex

@@ -0,0 +1,690 @@
+#!/bin/sh
+# ============================================================================
+# rnex — Repo Nexus CLI
+# Tooling-independent multi-repo workspace manager with auto-synced AI context.
+# Zero dependencies. POSIX-compatible.
+# ============================================================================
+set -e
+
+RNEX_VERSION="0.1.0"
+RNEX_CONFIG_FILE="rnex.yaml"
+
+# ---- Terminal Colours (auto-detected) -------------------------------------
+
+if [ -t 1 ]; then
+  _R='\033[0;31m' _G='\033[0;32m' _Y='\033[1;33m' _B='\033[0;34m' _C='\033[0;36m'
+  _BOLD='\033[1m' _DIM='\033[2m' _NC='\033[0m'
+else
+  _R='' _G='' _Y='' _B='' _C='' _BOLD='' _DIM='' _NC=''
+fi
+
+# ---- Logging ---------------------------------------------------------------
+
+log_ok()   { printf "${_G}[✓]${_NC} %s\n" "$1"; }
+log_warn() { printf "${_Y}[!]${_NC} %s\n" "$1"; }
+log_err()  { printf "${_R}[✗]${_NC} %s\n" "$1" >&2; }
+log_info() { printf "${_C}[i]${_NC} %s\n" "$1"; }
+log_dim()  { printf "${_DIM}    %s${_NC}\n" "$1"; }
+die()      { log_err "$1"; exit 1; }
+
+# ---- Path Utilities --------------------------------------------------------
+
+resolve_path() {
+  _input="$1"
+  case "$_input" in
+    \~/*) _input="$HOME/${_input#\~/}" ;;
+    \~)   _input="$HOME" ;;
+  esac
+  case "$_input" in
+    /*)
+      printf '%s' "$_input"
+      ;;
+    *)
+      if [ -d "$_input" ]; then
+        printf '%s' "$(cd "$_input" 2>/dev/null && pwd -P)"
+      else
+        _parent="$(cd "$(dirname "$_input")" 2>/dev/null && pwd -P)"
+        _base="$(basename "$_input")"
+        if [ "$_parent" = "/" ]; then
+          printf '/%s' "$_base"
+        else
+          printf '%s/%s' "$_parent" "$_base"
+        fi
+      fi
+      ;;
+  esac
+}
+
+# Resolve location of this script (follows symlinks)
+resolve_script_path() {
+  _src="$1"
+  while [ -L "$_src" ]; do
+    _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+    _src="$(readlink "$_src")"
+    case "$_src" in
+      /*) ;;
+      *)  _src="$_dir/$_src" ;;
+    esac
+  done
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  printf '%s/%s' "$_dir" "$(basename "$_src")"
+}
+
+SCRIPT_LOCATION="$(resolve_script_path "$0")"
+
+# ---- Workspace Detection (Context-Aware) ----------------------------------
+
+# Search for rnex.yaml in current directory or parent directories
+find_workspace_dir() {
+  _curr="$(pwd -P 2>/dev/null || pwd)"
+  while [ -n "$_curr" ] && [ "$_curr" != "/" ]; do
+    if [ -f "$_curr/$RNEX_CONFIG_FILE" ]; then
+      printf '%s' "$_curr"
+      return 0
+    fi
+    _curr="$(dirname "$_curr")"
+  done
+  if [ -f "/$RNEX_CONFIG_FILE" ]; then
+    printf '/'
+    return 0
+  fi
+  return 1
+}
+
+# Locate workspace root for active commands
+require_workspace() {
+  if [ -n "$CUSTOM_CONFIG" ]; then
+    _cfg_path="$(resolve_path "$CUSTOM_CONFIG")"
+    if [ ! -f "$_cfg_path" ]; then
+      die "Specified config file does not exist: $_cfg_path"
+    fi
+    NEXUS_DIR="$(cd -P "$(dirname "$_cfg_path")" 2>/dev/null && pwd -P)"
+    WORKSPACE_YAML="$_cfg_path"
+    _load_repos_dir
+    log_info "Using workspace at ${_BOLD}$NEXUS_DIR${_NC} ${_DIM}(via config: $WORKSPACE_YAML)${_NC}"
+    return 0
+  fi
+
+  _found_dir="$(find_workspace_dir || true)"
+  if [ -z "$_found_dir" ]; then
+    log_err "No '$RNEX_CONFIG_FILE' found in current directory ($PWD) or parent directories."
+    log_dim "To initialize a new Repo Nexus workspace here, run:"
+    log_dim "  rnex init"
+    log_dim "Or specify a workspace config file directly:"
+    log_dim "  rnex --config /path/to/$RNEX_CONFIG_FILE <command>"
+    log_dim "Or change directory to an existing workspace:"
+    log_dim "  cd /path/to/workspace"
+    exit 1
+  fi
+
+  NEXUS_DIR="$_found_dir"
+  WORKSPACE_YAML="$NEXUS_DIR/$RNEX_CONFIG_FILE"
+  _load_repos_dir
+
+  log_info "Using workspace at ${_BOLD}$NEXUS_DIR${_NC} ${_DIM}($RNEX_CONFIG_FILE found)${_NC}"
+}
+
+# Parse repos_dir from config, default to ./repos
+_load_repos_dir() {
+  _rd=""
+  if [ -f "$WORKSPACE_YAML" ]; then
+    _rd="$(awk '/^repos_dir:/ { sub(/^repos_dir:[ ]*/, ""); sub(/[ ]*#.*/, ""); print }' "$WORKSPACE_YAML")"
+  fi
+  _rd="${_rd:-./repos}"
+  case "$_rd" in
+    /*) REPOS_DIR="$_rd" ;;
+    *)  REPOS_DIR="$NEXUS_DIR/$_rd" ;;
+  esac
+}
+
+# ---- YAML Parser / Manipulator (for rnex.yaml) ----------------------------
+
+# Parse list of ai_files from rnex.yaml
+yaml_list_ai_files() {
+  [ -f "$WORKSPACE_YAML" ] || return 0
+  cat "$WORKSPACE_YAML" | awk '
+    /^ai_files:/ { a=1; next }
+    a && /^[^ #]/ { exit }
+    a && /^[ ]*-[ ]*/ {
+      sub(/^[ ]*-[ ]*/, "");
+      sub(/[ ]*#.*/, "");
+      if (length($0) > 0) print $0
+    }
+  '
+}
+
+# Parse list of repos from rnex.yaml
+yaml_list_repos() {
+  [ -f "$WORKSPACE_YAML" ] || return 0
+  cat "$WORKSPACE_YAML" | awk '
+    /^repos:/ { r=1; next }
+    r && /^[^ #]/ { exit }
+    r && /^  [a-zA-Z0-9_.-]+:[ ]*$/ {
+      sub(/^  /, ""); sub(/:.*/, ""); print
+    }
+  '
+}
+
+# Get a field value for a repo
+yaml_get() {
+  _repo="$1"; _field="$2"
+  [ -f "$WORKSPACE_YAML" ] || return 0
+  cat "$WORKSPACE_YAML" | awk -v repo="$_repo" -v field="$_field" '
+    /^repos:/ { r=1; next }
+    r && /^[^ #]/ { exit }
+    r && match($0, "^  " repo ":[ ]*$") { t=1; next }
+    r && t && /^  [^ #]/ { exit }
+    r && t && match($0, "^    " field ":") {
+      sub(/^    [a-zA-Z0-9_.-]+:[ ]*/, ""); print
+    }
+  '
+}
+
+yaml_has_repo() {
+  yaml_list_repos | grep -qx "$1" 2>/dev/null
+}
+
+yaml_add_repo() {
+  _name="$1"; _path="$2"
+  if ! grep -q '^repos:' "$WORKSPACE_YAML"; then
+    printf '\nrepos:\n' >> "$WORKSPACE_YAML"
+  fi
+  printf '  %s:\n    path: %s\n    scope: visible\n' \
+    "$_name" "$_path" >> "$WORKSPACE_YAML"
+}
+
+yaml_remove_repo() {
+  _name="$1"
+  _tmp="$(mktemp)"
+  awk -v name="$_name" '
+    /^repos:/ { r=1; print; next }
+    r && /^[^ #]/ { r=0 }
+    r && match($0, "^  " name ":[ ]*$") { skip=1; next }
+    r && skip && /^  [^ #]/ { skip=0 }
+    skip && /^    / { next }
+    { print }
+  ' "$WORKSPACE_YAML" > "$_tmp" && mv "$_tmp" "$WORKSPACE_YAML"
+}
+
+yaml_set() {
+  _repo="$1"; _field="$2"; _value="$3"
+  _tmp="$(mktemp)"
+  awk -v repo="$_repo" -v field="$_field" -v value="$_value" '
+    /^repos:/ { r=1; print; next }
+    r && /^[^ #]/ { r=0 }
+    r && match($0, "^  " repo ":[ ]*$") { t=1; print; next }
+    r && t && /^  [^ #]/ { t=0 }
+    r && t && match($0, "^    " field ":") {
+      printf "    %s: %s\n", field, value; next
+    }
+    { print }
+  ' "$WORKSPACE_YAML" > "$_tmp" && mv "$_tmp" "$WORKSPACE_YAML"
+}
+
+# ---- Symlink Operations ---------------------------------------------------
+
+ensure_repos_dir() { mkdir -p "$REPOS_DIR"; }
+
+create_scope_link() {
+  _name="$1"
+  _path="$(yaml_get "$_name" "path")"
+  [ -n "$_path" ] || die "No path recorded for repo '$_name'"
+  [ -d "$_path" ] || { log_warn "Path does not exist: $_path"; return 1; }
+  rm -f "$REPOS_DIR/$_name"
+  ln -s "$_path" "$REPOS_DIR/$_name"
+  log_ok "Linked scope: repos/$_name → $_path"
+}
+
+remove_scope_link() {
+  _name="$1"
+  if [ -L "$REPOS_DIR/$_name" ]; then
+    rm -f "$REPOS_DIR/$_name"
+    log_ok "Unlinked scope: repos/$_name"
+  fi
+}
+
+inject_ai_files() {
+  _name="$1"
+  _repo_path="$(yaml_get "$_name" "path")"
+  [ -n "$_repo_path" ] || die "No path recorded for repo '$_name'"
+  [ -d "$_repo_path" ] || die "Repo path does not exist: $_repo_path"
+
+  yaml_list_ai_files | while read -r _item; do
+    [ -n "$_item" ] || continue
+
+    _source="$NEXUS_DIR/$_item"
+    _target="$_repo_path/$_item"
+
+    if [ ! -e "$_source" ]; then
+      log_warn "AI file not found in nexus root, skipping: $_item"
+      continue
+    fi
+
+    if [ -e "$_target" ] && [ ! -L "$_target" ]; then
+      log_warn "Existing non-symlink file found, skipping: $_target"
+      continue
+    fi
+
+    _parent="$(dirname "$_target")"
+    [ -d "$_parent" ] || mkdir -p "$_parent"
+
+    rm -f "$_target"
+    ln -s "$_source" "$_target"
+    log_ok "Injected AI context: $_item → $(basename "$_repo_path")/$_item"
+  done
+
+  _gitignore_add "$_repo_path"
+}
+
+eject_ai_files() {
+  _name="$1"
+  _repo_path="$(yaml_get "$_name" "path")"
+  [ -n "$_repo_path" ] || die "No path recorded for repo '$_name'"
+
+  yaml_list_ai_files | while read -r _item; do
+    [ -n "$_item" ] || continue
+    _target="$_repo_path/$_item"
+    if [ -L "$_target" ]; then
+      rm -f "$_target"
+      log_ok "Ejected AI context: $_item from $(basename "$_repo_path")"
+    fi
+  done
+}
+
+_gitignore_add() {
+  _repo_path="$1"
+  _gi="$_repo_path/.gitignore"
+  _header_written=0
+
+  yaml_list_ai_files | while read -r _item; do
+    [ -n "$_item" ] || continue
+    if [ -f "$_gi" ] && grep -qxF "$_item" "$_gi" 2>/dev/null; then
+      continue
+    fi
+    if [ "$_header_written" -eq 0 ]; then
+      if [ ! -f "$_gi" ] || ! grep -q '# repo-nexus ai context' "$_gi" 2>/dev/null; then
+        printf '\n# repo-nexus ai context (injected symlinks)\n' >> "$_gi"
+      fi
+      _header_written=1
+    fi
+    printf '%s\n' "$_item" >> "$_gi"
+    log_dim "Added '$_item' to .gitignore in $(basename "$_repo_path")"
+  done
+}
+
+# ============================================================================
+# Commands
+# ============================================================================
+
+# ---- Known AI config files for auto-detection ------------------------------
+# Each entry: <file-or-dir-path>|<description>
+_AI_KNOWN_FILES="
+AGENTS.md|Universal AI agent instructions
+CLAUDE.md|Claude Code instructions
+.cursorrules|Cursor rules
+.cursor/rules|Cursor rules directory
+.windsurfrules|Windsurf rules
+.windsurf/rules|Windsurf rules directory
+.github/copilot-instructions.md|GitHub Copilot instructions
+.aider.conf.yml|Aider configuration
+CONVENTIONS.md|Coding conventions (Aider / general)
+.clinerules|Cline / Roo Code rules
+CODEX.md|Codex instructions
+.continue|Continue.dev configuration
+SKILL.md|Skills definition (emerging standard)
+"
+
+cmd_init() {
+  _target_dir="${1:-$PWD}"
+  _target_dir="$(resolve_path "$_target_dir")"
+  mkdir -p "$_target_dir"
+
+  _target_yaml="$_target_dir/$RNEX_CONFIG_FILE"
+
+  if [ -f "$_target_yaml" ]; then
+    log_warn "Workspace already initialized at $_target_dir ($RNEX_CONFIG_FILE exists)"
+    log_dim "To reconcile symlinks and AI files, run:"
+    log_dim "  rnex sync"
+    return 0
+  fi
+
+  # ---- Create AGENTS.md from sample if not present -------------------------
+  # (done before scanning so it gets auto-detected)
+  _target_agents="$_target_dir/AGENTS.md"
+  if [ ! -f "$_target_agents" ]; then
+    _script_dir="$(dirname "$SCRIPT_LOCATION")"
+    _sample="$_script_dir/docs/AGENTS.sample.md"
+    if [ -f "$_sample" ]; then
+      cp "$_sample" "$_target_agents"
+      log_ok "Created AGENTS.md from sample template"
+    else
+      cat <<'AGENTS_EOF' > "$_target_agents"
+# Multi-Repo AI Workspace Context
+
+This workspace operates as a **Repo Nexus** linking multiple independent repositories via symlinks.
+
+## Rules for AI Coding Assistants
+
+1. **Symlink Write-Through**: Files edited under `repos/<name>/` directly modify the target repository.
+2. **Repo Boundaries**: Each repository is isolated. Do not introduce cross-repo imports unless explicitly architected.
+3. **Shared Context**: This file is symlinked across member repositories. Keep instructions universal. Use local instructions for repo-specific rules.
+4. **Git Operations**: Commit and push changes directly within the respective member repository root.
+AGENTS_EOF
+      log_ok "Created AGENTS.md with default template"
+    fi
+  else
+    log_info "AGENTS.md already exists, skipping creation"
+  fi
+
+  # ---- Auto-detect existing AI config files --------------------------------
+  printf "\n${_BOLD}Scanning for existing AI configuration files...${_NC}\n"
+
+  # Display detected files
+  echo "$_AI_KNOWN_FILES" | while IFS='|' read -r _pattern _desc; do
+    [ -n "$_pattern" ] || continue
+    if [ -e "$_target_dir/$_pattern" ]; then
+      printf "  ${_G}✓${_NC} Found: ${_BOLD}%s${_NC}  ${_DIM}(%s)${_NC}\n" "$_pattern" "$_desc"
+    fi
+  done
+
+  # Build ai_files list from detection
+  _ai_yaml_lines=""
+  _any_detected=0
+  for _pattern in $(echo "$_AI_KNOWN_FILES" | awk -F'|' '{ gsub(/^[ ]+/, "", $1); if (length($1) > 0) print $1 }'); do
+    if [ -e "$_target_dir/$_pattern" ]; then
+      _ai_yaml_lines="${_ai_yaml_lines}  - ${_pattern}
+"
+      _any_detected=1
+    fi
+  done
+
+  if [ "$_any_detected" -eq 0 ]; then
+    log_info "No existing AI config files detected."
+    _ai_yaml_lines="  - AGENTS.md
+"
+  fi
+
+  # ---- Generate config file ------------------------------------------------
+  cat > "$_target_yaml" <<YAML_EOF
+# Repo Nexus workspace configuration
+# See docs/rnex.example.yaml for a comprehensive example with all options.
+
+# Directory for repository symlinks (relative to this file or absolute)
+repos_dir: ./repos
+
+# AI context files to automatically sync into member repositories.
+# These files are symlinked from this workspace root into each registered repo.
+ai_files:
+${_ai_yaml_lines}
+# Member repositories managed by Repo Nexus
+repos:
+YAML_EOF
+
+  # ---- Create repos directory -----------------------------------------------
+  _repos_dir="$_target_dir/repos"
+  mkdir -p "$_repos_dir"
+
+  printf '\n'
+  log_ok "Initialized Repo Nexus workspace at ${_BOLD}$_target_dir${_NC}"
+  log_dim "Created $RNEX_CONFIG_FILE and repos/"
+  printf '\n'
+  log_info "Next steps:"
+  log_dim "1. Edit $RNEX_CONFIG_FILE to configure your AI context files"
+  log_dim "2. Add repositories with: rnex add <name> <path>"
+  log_dim "3. See docs/rnex.example.yaml for a full configuration reference"
+}
+
+cmd_add() {
+  require_workspace
+  _name="$1"; _path="$2"
+  [ -n "$_name" ] || die "Usage: rnex add <name> <path>"
+  [ -n "$_path" ] || die "Usage: rnex add <name> <path>"
+
+  yaml_has_repo "$_name" && die "Repo '$_name' is already registered in $RNEX_CONFIG_FILE"
+
+  _path="$(resolve_path "$_path")"
+  [ -d "$_path" ] || die "Directory does not exist: $_path"
+
+  ensure_repos_dir
+  yaml_add_repo "$_name" "$_path"
+  create_scope_link "$_name"
+  inject_ai_files "$_name"
+  printf '\n'
+  log_ok "Registered and synchronized repo '${_name}'"
+}
+
+cmd_remove() {
+  require_workspace
+  _name="$1"
+  [ -n "$_name" ] || die "Usage: rnex remove <name>"
+  yaml_has_repo "$_name" || die "Repo '$_name' is not registered"
+
+  eject_ai_files "$_name"
+  remove_scope_link "$_name"
+  yaml_remove_repo "$_name"
+  log_ok "Unregistered repo '$_name' from $RNEX_CONFIG_FILE"
+}
+
+cmd_show() {
+  require_workspace
+  _name="$1"
+  [ -n "$_name" ] || die "Usage: rnex show <name>"
+  yaml_has_repo "$_name" || die "Repo '$_name' is not registered"
+
+  ensure_repos_dir
+  create_scope_link "$_name"
+  yaml_set "$_name" "scope" "visible"
+}
+
+cmd_hide() {
+  require_workspace
+  _name="$1"
+  [ -n "$_name" ] || die "Usage: rnex hide <name>"
+  yaml_has_repo "$_name" || die "Repo '$_name' is not registered"
+
+  remove_scope_link "$_name"
+  yaml_set "$_name" "scope" "hidden"
+}
+
+cmd_list() {
+  require_workspace
+  printf "${_B}%-25s %-12s %s${_NC}\n" "NAME" "SCOPE" "PATH"
+  printf '%-25s %-12s %s\n' "----" "-----" "----"
+  yaml_list_repos | while read -r _name; do
+    _scope="$(yaml_get "$_name" "scope")"
+    _path="$(yaml_get "$_name" "path")"
+    printf '%-25s %-12s %s\n' \
+      "$_name" "${_scope:-visible}" "$_path"
+  done
+}
+
+cmd_status() {
+  require_workspace
+  ensure_repos_dir
+
+  printf "\n${_B}Repo Nexus Workspace Status${_NC}\n"
+  printf '=%.0s' 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
+  printf '\n\n'
+
+  printf "${_BOLD}Configured AI Context Files ($RNEX_CONFIG_FILE):${_NC}\n"
+  yaml_list_ai_files | while read -r _item; do
+    if [ -e "$NEXUS_DIR/$_item" ]; then
+      printf "  ${_G}✓${_NC} %s\n" "$_item"
+    else
+      printf "  ${_R}✗${_NC} %s (missing from nexus root)\n" "$_item"
+    fi
+  done
+  printf '\n'
+
+  printf "${_BOLD}Member Repositories:${_NC}\n"
+  if [ -z "$(yaml_list_repos)" ]; then
+    printf "  ${_DIM}(No repositories registered yet. Use 'rnex add <name> <path>')${_NC}\n"
+  else
+    yaml_list_repos | while read -r _name; do
+      _scope="$(yaml_get "$_name" "scope")"
+      _path="$(yaml_get "$_name" "path")"
+      _link="$REPOS_DIR/$_name"
+
+      if [ "$_scope" = "hidden" ]; then
+        printf "  ${_Y}○${_NC} %-22s ${_DIM}hidden${_NC}\n" "$_name"
+      elif [ -L "$_link" ] && [ -d "$_link" ]; then
+        printf "  ${_G}●${_NC} %-22s ${_G}active${_NC} → %s\n" "$_name" "$_path"
+      elif [ -L "$_link" ]; then
+        printf "  ${_R}✗${_NC} %-22s ${_R}BROKEN LINK${_NC} → %s\n" "$_name" "$_path"
+      else
+        printf "  ${_R}✗${_NC} %-22s ${_R}MISSING LINK${_NC} (run 'rnex sync')\n" "$_name"
+      fi
+    done
+  fi
+
+  printf "\n${_DIM}Workspace:   %s${_NC}\n" "$NEXUS_DIR"
+  printf "${_DIM}Repos Dir:   %s${_NC}\n" "$REPOS_DIR"
+  printf "${_DIM}Config:      %s${_NC}\n\n" "$WORKSPACE_YAML"
+}
+
+cmd_sync() {
+  require_workspace
+  ensure_repos_dir
+
+  log_info "Synchronizing workspace from $RNEX_CONFIG_FILE..."
+  yaml_list_repos | while read -r _name; do
+    _scope="$(yaml_get "$_name" "scope")"
+
+    if [ "$_scope" = "hidden" ]; then
+      remove_scope_link "$_name"
+    else
+      create_scope_link "$_name" || true
+    fi
+
+    inject_ai_files "$_name" || true
+  done
+
+  log_ok "Sync complete — all scope links and AI context files reconciled"
+}
+
+cmd_install() {
+  _target_bin="${1:-$HOME/.local/bin}"
+  _target_bin="$(resolve_path "$_target_bin")"
+
+  mkdir -p "$_target_bin" 2>/dev/null || true
+  if [ -d "$_target_bin" ] && [ -w "$_target_bin" ]; then
+    if [ -e "$_target_bin/rnex" ] && [ "$(resolve_script_path "$_target_bin/rnex" 2>/dev/null)" = "$SCRIPT_LOCATION" ]; then
+      log_ok "'rnex' is already installed at ${_BOLD}$_target_bin/rnex${_NC}"
+    else
+      rm -f "$_target_bin/rnex" "$_target_bin/repo-nexus"
+      ln -sf "$SCRIPT_LOCATION" "$_target_bin/rnex" 2>/dev/null || cp "$SCRIPT_LOCATION" "$_target_bin/rnex"
+      ln -sf "$SCRIPT_LOCATION" "$_target_bin/repo-nexus" 2>/dev/null || cp "$SCRIPT_LOCATION" "$_target_bin/repo-nexus"
+      chmod +x "$_target_bin/rnex" "$_target_bin/repo-nexus" 2>/dev/null || true
+      log_ok "Installed 'rnex' and 'repo-nexus' into ${_BOLD}$_target_bin${_NC}"
+    fi
+  else
+    log_warn "Cannot write to $_target_bin."
+    log_info "You can manually create an alias in your shell profile (~/.zshrc or ~/.bashrc):"
+    log_dim "  alias rnex=\"$SCRIPT_LOCATION\""
+    log_dim "  alias repo-nexus=\"$SCRIPT_LOCATION\""
+    return 1
+  fi
+
+  case ":$PATH:" in
+    *":$_target_bin:"*)
+      log_ok "$_target_bin is in your PATH"
+      ;;
+    *)
+      log_warn "$_target_bin is not in your current PATH."
+      log_dim "Add this line to your shell profile (~/.zshrc or ~/.bashrc):"
+      log_dim "  export PATH=\"$_target_bin:\$PATH\""
+      ;;
+  esac
+}
+
+cmd_version() {
+  printf "rnex %s\n" "$RNEX_VERSION"
+}
+
+cmd_help() {
+  cat <<EOF
+
+  rnex — Repo Nexus CLI  (v$RNEX_VERSION)
+  Tooling-independent multi-repo workspace manager with shared AI context.
+
+  USAGE
+    rnex [options] <command> [arguments]
+
+  OPTIONS
+    -c, --config <file>     Path to $RNEX_CONFIG_FILE (executes in the directory where config lives)
+    -h, --help              Show help information
+    -v, --version           Show version
+
+  WORKSPACE & SYSTEM SETUP
+    init [dir]              Initialize a new Repo Nexus workspace in current (or specified) dir
+    install [dir]           Install rnex & repo-nexus globally into ~/.local/bin (or custom dir)
+    sync                    Reconcile scope links & AI files from $RNEX_CONFIG_FILE
+
+  REPO MANAGEMENT
+    add <name> <path>       Register local repo, link to scope & auto-inject AI context
+    remove <name>           Unregister repo, unlink scope & clean up injected AI files
+    list                    List all registered member repos
+    status                  Inspect workspace health, active repos, and AI context files
+
+  VISIBILITY CONTROL
+    show <name>             Make repo visible in workspace (creates repos/<name> link)
+    hide <name>             Hide repo from workspace scope (removes repos/<name> link)
+
+  EXAMPLES
+    rnex init                                 # Initialize workspace in current folder
+    rnex install                              # Install rnex CLI globally to ~/.local/bin
+    rnex add my-app ~/code/my-app             # Register repo (links & syncs AI context)
+    rnex add my-app ../my-app                 # Register repo (relative path)
+    rnex --config /path/to/rnex.yaml list     # Operate on a specific workspace directly
+    rnex hide my-app                          # Temporarily hide from active indexing
+    rnex show my-app                          # Bring back into active scope
+    rnex sync                                 # Reconcile all links from $RNEX_CONFIG_FILE
+
+EOF
+}
+
+# ============================================================================
+# Entry Point & Option Parsing
+# ============================================================================
+
+CUSTOM_CONFIG=""
+[ -n "$RNEX_CONFIG" ] && CUSTOM_CONFIG="$RNEX_CONFIG"
+
+# Filter --config / -c flags
+ORIG_COUNT=$#
+i=0
+while [ "$i" -lt "$ORIG_COUNT" ]; do
+  i=$((i + 1))
+  case "$1" in
+    --config=*)
+      CUSTOM_CONFIG="${1#*=}"
+      shift
+      ;;
+    --config|-c)
+      [ -n "$2" ] || die "Option $1 requires a file path argument"
+      CUSTOM_CONFIG="$2"
+      shift 2
+      i=$((i + 1))
+      ;;
+    *)
+      _arg="$1"
+      shift
+      set -- "$@" "$_arg"
+      ;;
+  esac
+done
+
+case "${1:-help}" in
+  init)        shift; cmd_init "$@" ;;
+  install)     shift; cmd_install "$@" ;;
+  add)         shift; cmd_add "$@" ;;
+  remove)      shift; cmd_remove "$@" ;;
+  show)        shift; cmd_show "$@" ;;
+  hide)        shift; cmd_hide "$@" ;;
+  list)        shift; cmd_list "$@" ;;
+  status)      shift; cmd_status "$@" ;;
+  sync)        shift; cmd_sync "$@" ;;
+  version|-v|--version) cmd_version ;;
+  help|-h|--help) cmd_help ;;
+  *)           die "Unknown command: $1 (try 'rnex help')" ;;
+esac