repo-nexus 0.4.7 → 0.5.2

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to Repo Nexus (`rnex`) will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.1] - 2026-10-08
+
+### Added
+- Comprehensive CLI Reference Manual (`docs/CLI.md`) documenting all workspace lifecycle commands, member repository operations, automated Git hooks, scoped plugins, standardized prompts catalog, and shell completion recipes.
+
+### Fixed
+- Dynamic version matching in test suite (`tests/test_cli.sh`, Test 26) resolving hardcoded version assertion on `package.json` bumps.
+- Default version fallback in `rnex` CLI aligned with `package.json`.
+
+## [0.5.0] - 2026-10-08
+
+### Added
+- **Version-Aware Upgrade System (`rnex update` / `rnex upgrade` and `rnex fix`)**:
+  - Automatically compares workspace configuration against the running CLI version using semantic versioning.
+  - Interactive upgrade prompt (`[y/N]`, bypassable with `-y` or `--yes`).
+  - Non-destructively inserts missing schema keys (`version`, `ai_instructions`, `code_workspace`) while preserving comments and repo mappings.
+  - Updates routing instructions in `AGENTS.md`, `CLAUDE.md`, and other detected AI assistant instruction files.
+- **Config-Driven Automated Git Hooks (`rnex hooks`)**:
+  - Native Git hooks managed under `.rnex/hooks/` via `git config core.hooksPath .rnex/hooks`.
+  - Dynamic dispatchers for `post-merge`, `post-commit`, `pre-commit`, and `pre-push` that evaluate workspace triggers defined in `rnex.yaml` and `.local.rnex.yaml`.
+  - Automated `post-merge` hook runs `rnex fix -y --quiet` to keep member clones and plugin scopes in sync after pulling team changes.
+  - Subcommands: `rnex hooks install`, `rnex hooks uninstall`, and `rnex hooks status`.
+  - Interactive hooks setup prompt during `rnex init` (controllable via `--hooks` and `--no-hooks` flags).
+  - Health check integrated into `rnex status` reporting active hooks and triggers.
+- **Standardized Prompts Suite & Master Catalog (`toolkit/prompts/`)**:
+  - Master index catalog at `toolkit/prompts/index.md` (synced to `.rnex/prompts/index.md`).
+  - New workflow prompts:
+    - `rnex-cross-repo-feature.md`: Multi-repository feature planning and contract implementation.
+    - `rnex-workspace-audit.md`: Multi-repo status, branch tracking, and configuration validation.
+    - `rnex-wiki-ingest.md`: Autonomous intake decomposition into atomic Karpathy LLM Wiki pages.
+    - `rnex-wiki-lint.md`: Graph integrity validation, backlink recalculation, and index rebuilding.
+    - `rnex-setup-karpathy-wiki.md`: Deterministic knowledge base scaffolding.
+  - Workspace `AGENTS.md` and `CLAUDE.md` maintain a minimal 1-line pointer to `.rnex/prompts/index.md` to conserve agent context.
+- **Mandatory Session Startup Protocol**:
+  - Enforced hard-gate instruction block in `AGENTS.md` and `CLAUDE.md` requiring AI coding assistants to inspect configuration (`.local.rnex.yaml`, `rnex.yaml`), plugin guidelines, and orientation notes (`wiki/hot.md` and `wiki/index.md`) before taking task actions.
+
+## [0.4.7] - 2026-10-06
+
+### Fixed
+- Quoted variable expansion in parameter pattern removal (`_repos_rel="${REPOS_DIR#"$NEXUS_DIR"/}"`) resolving ShellCheck SC2295.
+
+## [0.4.6] - 2026-10-06
+
+### Added
+- **Configurable AI Instructions Routing** (`ai_instructions` in `rnex.yaml`):
+  - Support custom instruction files (e.g. `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, defaulting to `AGENTS.md`).
+  - `rnex status` detects and highlights missing instruction files.
+  - `rnex init` supports `--ai <file>` flag.
+- **VS Code & Cursor Multi-Root Workspace Support** (`code_workspace` in `rnex.yaml`):
+  - Automatically generates and synchronizes `.code-workspace` files mapping the workspace root and active member repositories.
+  - `rnex init` supports `--code-workspace [file]` flag.
+
+## [0.4.5] - 2026-10-06
+
+### Fixed
+- Guaranteed deterministic workspace initialization by tracking `repos/.gitkeep`.
+- Prevented empty member directory creation during init.
+
+## [0.4.4] - 2026-10-06
+
+### Documentation
+- Standardized deterministic Karpathy LLM Wiki initialization in `toolkit/plugins/karpathy-llm/`.
+
+## [0.4.3] - 2026-10-05
+
+### Refactored
+- Separated behavioral rules (`rules/behavioral.md`) from architectural specifications (`instructions/wiki-architecture.md`) in `karpathy-llm` plugin.
+
+## [0.4.2] - 2026-10-05
+
+### Fixed
+- Updated automated CLI test suite to dynamically inspect version from `package.json`.
+
+## [0.4.1] - 2026-10-05
+
+### Added
+- Streamlined delimited routing protocol in `AGENTS.md` (`<!-- REPO-NEXUS:START -->` / `<!-- REPO-NEXUS:END -->`).
+- Automated `.gitignore` reconciliation stripping legacy counters and ensuring `.rnex/` encapsulation.
+- Purged legacy symlink mechanics in favor of physical autonomy.
+
+## [0.4.0] - 2026-10-05
+
+### Added
+- **Virtual Meta-Repo 2.0**:
+  - Physical member repository clones in `./repos/<name>` with complete Git isolation (no submodules).
+  - Two-level configuration (`rnex.yaml` team manifest and `.local.rnex.yaml` machine overrides).
+  - Cross-repository batch execution (`rnex exec <command...>`).
+  - Member repository state management (`rnex enable`, `rnex disable`, `rnex list`, `rnex remove`).
+  - Scoped workspace plugins (`.rnex/plugins/<plugin-name>/`).

package/README.md

@@ -6,6 +6,7 @@
 [![POSIX Compatible](https://img.shields.io/badge/POSIX-compatible-success)](#)
 [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#)
 [![FAQ](https://img.shields.io/badge/docs-FAQ-blue.svg)](docs/FAQ.md)
+[![CLI Reference](https://img.shields.io/badge/docs-CLI%20Reference-blue.svg)](docs/CLI.md)
 
 A **simple, lightweight Virtual Meta-Repo companion** for multi-repo workspaces and shared AI context. It organizes independent repositories into a unified workspace and shares lean routing instructions (`AGENTS.md`) **without Git submodules, monorepo migrations, or symlink fragility**.
 
@@ -17,7 +18,9 @@ A **simple, lightweight Virtual Meta-Repo companion** for multi-repo workspaces
 - **Scoped Plugins & Context Packs**: Modular plugin packages scoped under `.rnex/plugins/<plugin-name>/` with support for domain directories (e.g. `raw/` and `wiki/` for `karpathy-llm`).
 - **Zero Dependencies**: Pure POSIX shell CLI (`rnex`). Works out of the box across macOS, Linux, and Windows (WSL/Git Bash).
 
-> 💡 **Have questions?** Check out the **[Frequently Asked Questions (FAQ)](docs/FAQ.md)** for architecture deep dives, Git workflows, and AI context strategies.
+> 💡 **Documentation & Guides:**
+> - Check out the **[CLI Reference Manual](docs/CLI.md)** for complete command syntax, flags, Git hooks, plugins, and prompts.
+> - Check out the **[Frequently Asked Questions (FAQ)](docs/FAQ.md)** for architecture deep dives, Git workflows, and AI context strategies.
 
 ---
 
@@ -32,6 +35,7 @@ A **simple, lightweight Virtual Meta-Repo companion** for multi-repo workspaces
 - [Plugins & Scoped Context Packs](#plugins--scoped-context-packs)
 - [Two-Level Configuration (`rnex.yaml` & `.local.rnex.yaml`)](#two-level-configuration)
 - [CLI Command Reference](#cli-command-reference)
+- [Full CLI Reference Manual (docs/CLI.md)](docs/CLI.md)
 - [Shell Auto-Completion](#shell-auto-completion)
 - [Project Structure](#project-structure)
 - [Running Tests](#running-tests)
@@ -272,6 +276,8 @@ repos:
 
 ## CLI Command Reference
 
+> 📖 **Full Manual Available:** See the comprehensive **[CLI Reference Manual](docs/CLI.md)** for exhaustive details, deep dives into every command and flag, lifecycle behaviors, automated Git hooks, scoped plugins, standardized prompts catalog, and shell completion recipes.
+
 ### Global Options
 | Option | Description |
 |:---|:---|
@@ -282,7 +288,7 @@ repos:
 ### Commands
 | Command | Description |
 |:---|:---|
-| `rnex init [-y] [dir]` | Initialize a new Virtual Meta-Repo workspace in current (or target) directory |
+| `rnex init [-y] [--ai <file>] [--code-workspace [file]] [--hooks\|--no-hooks] [dir]` | Initialize a new Virtual Meta-Repo workspace in current (or target) directory |
 | `rnex install [dir]` | Install `rnex` & `repo-nexus` globally into `~/.local/bin` (or custom dir) |
 | `rnex add [--local] [--disabled] <name> <git-url>` | Register and clone repo into `./repos/<name>` |
 | `rnex clone` | Clone all missing enabled repositories declared in `rnex.yaml` |
@@ -291,9 +297,11 @@ repos:
 | `rnex enable [--local] <name>` | Enable a repository in active workspace |
 | `rnex disable [--local] <name>` | Disable a repository from active workspace |
 | `rnex list` | List all member repositories with clone state, active branch, and `.rnex` status |
-| `rnex status` | Inspect workspace health, active repos, config loaded, and plugins |
+| `rnex status` | Inspect workspace health, active repos, config loaded, git hooks, and plugins |
 | `rnex rnex-dir <enable\|disable> <name>` | Toggle `.rnex/` directory integration for a member repository |
-| `rnex fix` (or `sync`) | Reconcile workspace repositories, plugins, and member `.rnex/` directories |
+| `rnex fix [-y] [--quiet]` (or `sync`) | Reconcile workspace repositories, plugins, prompts, and member `.rnex/` directories |
+| `rnex update [-y]` (or `upgrade`) | Safely upgrade workspace configuration schema and routing instructions |
+| `rnex hooks <install\|uninstall\|status>` | Manage config-driven automated Git hooks (`.rnex/hooks`) |
 | `rnex plugin <list\|info\|enable\|disable>` | Manage workspace plugins |
 | `rnex completion <bash\|zsh\|fish>` | Generate shell auto-completion script |
 
@@ -330,17 +338,20 @@ repo-nexus/
 ├── package.json                    # npm package manifest (single version source of truth)
 ├── rnex                            # CLI executable (POSIX shell)
 ├── AGENTS.md                       # Routing-only universal AI instructions
+├── CHANGELOG.md                    # Release history and migration notes
 ├── docs/
 │   ├── AGENTS.sample.md            # Template for routing-only AGENTS.md
+│   ├── CLI.md                      # Comprehensive CLI reference manual
 │   ├── FAQ.md                      # Frequently Asked Questions
 │   └── rnex.example.yaml           # Full config reference with examples
 ├── .github/
 │   └── workflows/ci.yml            # GitHub Actions CI workflow
 ├── tests/
 │   └── test_cli.sh                 # Automated CLI test suite
-├── toolkit/                        # Shared plugins and templates
-│   └── plugins/
-│       └── karpathy-llm/           # Scoped Karpathy LLM plugin
+├── toolkit/                        # Shared plugins, prompts, and templates
+│   ├── plugins/
+│   │   └── karpathy-llm/           # Scoped Karpathy LLM plugin
+│   └── prompts/                    # Standardized AI operational prompts
 └── README.md
 ```
 

package/docs/CLI.md

@@ -0,0 +1,383 @@
+# Repo Nexus (`rnex`) CLI Reference Manual
+
+`rnex` is a lightweight, zero-dependency command-line utility built entirely in pure POSIX shell (`/bin/sh`). It orchestrates **Virtual Meta-Repo** workspaces, manages autonomous member repository clones, automates multi-repo Git workflows, and coordinates AI routing instructions without Git submodules.
+
+---
+
+## Table of Contents
+
+- [Overview & Global Options](#overview--global-options)
+- [Workspace Lifecycle Commands](#workspace-lifecycle-commands)
+  - [`rnex init`](#rnex-init)
+  - [`rnex status`](#rnex-status)
+  - [`rnex fix` (alias: `sync`)](#rnex-fix-alias-sync)
+  - [`rnex update` (alias: `upgrade`)](#rnex-update-alias-upgrade)
+  - [`rnex install`](#rnex-install)
+  - [`rnex completion`](#rnex-completion)
+  - [`rnex version`](#rnex-version)
+- [Member Repository Commands](#member-repository-commands)
+  - [`rnex add`](#rnex-add)
+  - [`rnex clone`](#rnex-clone)
+  - [`rnex exec`](#rnex-exec)
+  - [`rnex list`](#rnex-list)
+  - [`rnex enable`](#rnex-enable)
+  - [`rnex disable`](#rnex-disable)
+  - [`rnex remove`](#rnex-remove)
+  - [`rnex rnex-dir`](#rnex-rnex-dir)
+- [Git Hooks Automation Commands](#git-hooks-automation-commands)
+  - [`rnex hooks install`](#rnex-hooks-install)
+  - [`rnex hooks status`](#rnex-hooks-status)
+  - [`rnex hooks uninstall`](#rnex-hooks-uninstall)
+- [Plugin Management Commands](#plugin-management-commands)
+  - [`rnex plugin list`](#rnex-plugin-list)
+  - [`rnex plugin info`](#rnex-plugin-info)
+  - [`rnex plugin enable`](#rnex-plugin-enable)
+  - [`rnex plugin disable`](#rnex-plugin-disable)
+- [Standardized Prompts Catalog](#standardized-prompts-catalog)
+- [Environment Variables & Exit Codes](#environment-variables--exit-codes)
+
+---
+
+## Overview & Global Options
+
+### Syntax
+```sh
+rnex [global-options] <command> [command-options] [arguments]
+```
+
+### Global Options
+
+| Option | Shorthand | Description |
+|:---|:---|:---|
+| `--config <file>` | `-c <file>` | Path to a custom workspace configuration file (e.g. `/path/to/rnex.yaml`). Executes as if running from the directory containing that configuration file. |
+| `--help` | `-h` | Display summary help and command usage. |
+| `--version` | `-v` | Display the current version of the CLI. |
+
+---
+
+## Workspace Lifecycle Commands
+
+### `rnex init`
+
+Initializes a new Repo Nexus Virtual Meta-Repo workspace.
+
+```sh
+rnex init [options] [directory]
+```
+
+#### Arguments & Options
+- `directory` *(optional)*: Target directory to initialize. Defaults to current working directory (`$PWD`).
+- `-y`, `--yes`: Non-interactive mode. Accepts all defaults automatically without prompting.
+- `--ai <filename>`, `--instructions <filename>`: Name of the primary AI instructions file (e.g. `CLAUDE.md`, `GEMINI.md`, `.cursorrules`). Default: `AGENTS.md`.
+- `--code-workspace [filename]`: Enable VS Code / Cursor multi-root workspace file generation. Defaults to `<directory-name>.code-workspace` if omitted.
+- `--hooks`: Force-enable automated Git hooks setup during initialization.
+- `--no-hooks`: Skip Git hooks configuration during initialization.
+
+#### What it does:
+1. Creates `rnex.yaml` with schema versioning (`version: <version>`), `repos_dir: ./repos`, and configured defaults.
+2. Merges Repo Nexus routing instructions (`<!-- REPO-NEXUS:START -->` ... `<!-- REPO-NEXUS:END -->`) into the target AI instructions file.
+3. Creates `./repos/` directory with a tracked `.gitkeep`.
+4. Creates `.rnex/`, `.rnex/plugins/`, and copies standardized prompts to `.rnex/prompts/`.
+5. Reconciles `.gitignore` to ensure `repos/`, `.rnex/`, and `.local.rnex.yaml` are never tracked by the meta-repo.
+6. Generates a multi-root `.code-workspace` file if configured.
+7. Prompts to configure automated workspace Git hooks (`core.hooksPath = .rnex/hooks`) if inside a Git repository.
+
+#### Examples:
+```sh
+# Initialize in current directory with interactive prompts
+rnex init
+
+# Non-interactive initialization for CI or automated setup
+rnex init -y
+
+# Initialize for Anthropic Claude Code with automated Git hooks
+rnex init -y --ai CLAUDE.md --hooks
+
+# Initialize with VS Code multi-root workspace support
+rnex init --code-workspace my-team.code-workspace
+```
+
+---
+
+### `rnex status`
+
+Performs a comprehensive diagnostic and health check on the active workspace.
+
+```sh
+rnex status
+```
+
+#### What it reports:
+- **Configuration & Versions**: Path, version tag, and load status of `rnex.yaml` and `.local.rnex.yaml`.
+- **Paths**: Clones directory (`repos_dir`) and primary AI instructions file.
+- **Git Integration**: Validation that `.gitignore` ignores `repos/`, `.rnex/`, and local files, and whether `core.hooksPath` points to `.rnex/hooks`.
+- **AI Routing Context**: Existence and routing block markers in `AGENTS.md`, `CLAUDE.md`, `.code-workspace`, and prompts catalog (`.rnex/prompts/index.md`).
+- **Active Plugins**: List of enabled plugins, scoped versions, and asset directories.
+- **Member Repositories**: Every registered repository, enabled/disabled state, clone health, and active Git branch.
+
+---
+
+### `rnex fix` (alias: `sync`)
+
+Reconciles the workspace configuration, instructions, prompts, plugins, and member clones.
+
+```sh
+rnex fix [options]
+```
+
+#### Options:
+- `-y`, `--yes`: Automatically confirm configuration schema upgrades if an older workspace version is detected.
+- `-q`, `--quiet`: Quiet mode; suppresses non-error informational messages (used in background Git hooks).
+- `--upgrade`: Explicitly triggers version upgrade reconciliation.
+
+#### What it reconciles:
+1. **Version Upgrade Check**: If workspace configuration version is older than running CLI, prompts to upgrade non-destructively.
+2. **Git Ignore**: Ensures `repos/`, `.rnex/`, and local config files are ignored, stripping legacy counters.
+3. **Routing Instructions**: Replaces or inserts the delimited Repo Nexus routing block in `AGENTS.md`, `CLAUDE.md`, etc.
+4. **Prompts Synchronization**: Copies standard workflow prompts into `.rnex/prompts/`.
+5. **Git Hooks**: Re-syncs hook scripts in `.rnex/hooks/` if active.
+6. **Plugins**: Scopes plugin templates, instructions, and rules to `.rnex/plugins/<plugin>/`.
+7. **Member Repositories**: Ensures member `.rnex/` directories exist where enabled.
+8. **VS Code / Cursor Workspace**: Regenerates folder mappings in the `.code-workspace` file.
+
+---
+
+### `rnex update` (alias: `upgrade`)
+
+Safely updates an existing workspace's configuration schema and routing instructions to match the currently installed CLI version.
+
+```sh
+rnex update [-y]
+```
+
+- Compares `version:` in `rnex.yaml` with the running `rnex` CLI version.
+- Non-destructively updates the `version:` key and inserts newly introduced schema keys (`ai_instructions`, `code_workspace`) while strictly preserving existing comments, indentation, and repository declarations.
+- Reconciles AI instructions in `AGENTS.md` / `CLAUDE.md` to the newest standard.
+
+---
+
+### `rnex install`
+
+Installs the `rnex` and `repo-nexus` executables into a system bin directory.
+
+```sh
+rnex install [bin-directory]
+```
+
+- Default directory: `~/.local/bin`
+- Creates symlinks for both `rnex` and `repo-nexus`.
+
+---
+
+### `rnex completion`
+
+Generates shell completion scripts for Tab auto-completion.
+
+```sh
+rnex completion <bash|zsh|fish>
+```
+
+#### Setup:
+- **Zsh** (in `~/.zshrc`):
+  ```sh
+  source <(rnex completion zsh)
+  ```
+- **Bash** (in `~/.bashrc`):
+  ```sh
+  source <(rnex completion bash)
+  ```
+- **Fish** (in `~/.config/fish/config.fish`):
+  ```sh
+  rnex completion fish | source
+  ```
+
+---
+
+### `rnex version`
+
+Outputs the version number of the `rnex` CLI.
+
+```sh
+rnex version
+# or:
+rnex -v
+```
+
+---
+
+## Member Repository Commands
+
+### `rnex add`
+
+Registers a repository in the workspace configuration and immediately clones it into `./repos/<name>`.
+
+```sh
+rnex add [options] <name> <git-url>
+```
+
+#### Options:
+- `--local`: Registers the repository in `.local.rnex.yaml` instead of `rnex.yaml` (machine-specific, not committed to Git).
+- `--disabled`: Registers the repository but flags it `enabled: false` (not cloned until enabled).
+- `--no-rnex-dir`: Sets `rnex_dir: false`, leaving the member repository completely untouched without a member `.rnex/` directory.
+
+#### Examples:
+```sh
+# Register and clone a team repository
+rnex add backend git@github.com:myorg/backend-api.git
+
+# Register a private experiment on local machine only
+rnex add --local experiment git@github.com:myorg/exp.git
+```
+
+---
+
+### `rnex clone`
+
+Clones any registered, enabled repository that is currently missing on disk.
+
+```sh
+rnex clone
+```
+
+Teammates who clone the meta-repo run `rnex clone` to fetch all member repositories in a single step.
+
+---
+
+### `rnex exec`
+
+Executes an arbitrary shell command across all active (enabled) member repositories in parallel or sequential order.
+
+```sh
+rnex exec <command...>
+```
+
+#### Examples:
+```sh
+# Check Git status across all member repositories
+rnex exec git status -s
+
+# Pull latest commits on active branch across all repos
+rnex exec git pull --ff-only
+
+# Run tests in all member repos
+rnex exec npm test
+```
+
+---
+
+### `rnex list`
+
+Lists all registered member repositories with their clone status, active Git branch, and member `.rnex` state.
+
+```sh
+rnex list
+```
+
+---
+
+### `rnex enable` & `rnex disable`
+
+Toggles whether a member repository is active in the workspace.
+
+```sh
+# Enable a repository
+rnex enable [--local] <name>
+
+# Disable a repository
+rnex disable [--local] <name>
+```
+
+- When disabled, a repository is excluded from `rnex clone`, `rnex exec`, and AI agent routing.
+- `--local`: Writes the override into `.local.rnex.yaml`, allowing individual developers to disable repositories on their workstation without affecting teammates.
+
+---
+
+### `rnex remove`
+
+Unregisters a member repository from configuration and deletes its clone from disk.
+
+```sh
+rnex remove <name>
+```
+
+Prompts for interactive confirmation before deleting files.
+
+---
+
+### `rnex rnex-dir`
+
+Toggles `.rnex/` directory integration inside a specific member repository (`repos/<name>/.rnex/`).
+
+```sh
+rnex rnex-dir <enable|disable> <name>
+```
+
+---
+
+## Git Hooks Automation Commands
+
+Repo Nexus manages workspace-level Git hooks via `git config core.hooksPath .rnex/hooks`. The hooks are native shell scripts that dynamically evaluate configuration triggers in `rnex.yaml` and `.local.rnex.yaml`.
+
+```sh
+rnex hooks <install|uninstall|status>
+```
+
+### Subcommands
+
+#### `rnex hooks install`
+Installs native hook dispatchers into `.rnex/hooks/` and configures Git:
+- **`post-merge`**: Automatically runs `rnex fix -y --quiet` whenever you run `git pull` or merge upstream changes, ensuring new repositories or plugin additions sync instantly.
+- **`post-commit`**: Evaluates `lint_trigger: git-post-commit`. If `/raw/` or `/wiki/` files were committed, alerts the user to run maintenance workflows.
+- **`pre-commit`**: Evaluates `lint_trigger: git-pre-commit`. Validates staged files before committing.
+- **`pre-push`**: Evaluates `lint_trigger: git-pre-push`. Validates changes before pushing to remote.
+
+#### `rnex hooks status`
+Displays the active `core.hooksPath`, installed hook scripts, and plugin triggers detected in `rnex.yaml`.
+
+#### `rnex hooks uninstall`
+Unsets `core.hooksPath` in Git configuration and removes `.rnex/hooks/`.
+
+---
+
+## Plugin Management Commands
+
+Repo Nexus features a modular plugin architecture where plugin rules, instructions, and templates are scoped strictly under `.rnex/plugins/<plugin-name>/`.
+
+```sh
+rnex plugin <list|info|enable|disable> [name]
+```
+
+### Subcommands
+- **`rnex plugin list`**: Displays all available plugins distributed with `rnex` and highlights enabled plugins.
+- **`rnex plugin info <name>`**: Shows description, version, scoped directory, and external template paths for a plugin.
+- **`rnex plugin enable <name>`**: Enables a plugin in `rnex.yaml`, copies assets to `.rnex/plugins/<name>/`, and reconciles workspace files.
+- **`rnex plugin disable <name>`**: Removes plugin assets from `.rnex/plugins/<name>/` and disables the plugin in `rnex.yaml`.
+
+---
+
+## Standardized Prompts Catalog
+
+Repo Nexus provides a standardized suite of operational prompt templates in `toolkit/prompts/` that sync to `.rnex/prompts/` during `rnex fix` or `rnex init`.
+
+AI assistants navigate workflows via the catalog index at `.rnex/prompts/index.md`:
+
+| Prompt File | Purpose |
+|:---|:---|
+| [`index.md`](file:///Users/admin/Projects/ai/repo-nexus/toolkit/prompts/index.md) | Master catalog indexing all available workflows and prompts. |
+| [`rnex-cross-repo-feature.md`](file:///Users/admin/Projects/ai/repo-nexus/toolkit/prompts/rnex-cross-repo-feature.md) | Structured workflow for implementing cross-cutting features across multiple repos. |
+| [`rnex-workspace-audit.md`](file:///Users/admin/Projects/ai/repo-nexus/toolkit/prompts/rnex-workspace-audit.md) | Health, git dirty status, branch tracking, and configuration audit workflow. |
+| [`rnex-wiki-ingest.md`](file:///Users/admin/Projects/ai/repo-nexus/toolkit/prompts/rnex-wiki-ingest.md) | Autonomous ingestion of source docs from `/raw/` into Karpathy LLM Wiki pages. |
+| [`rnex-wiki-lint.md`](file:///Users/admin/Projects/ai/repo-nexus/toolkit/prompts/rnex-wiki-lint.md) | Link validation, backlink (`mentioned_in`) recalculation, and index rebuilding. |
+| [`rnex-setup-karpathy-wiki.md`](file:///Users/admin/Projects/ai/repo-nexus/toolkit/prompts/rnex-setup-karpathy-wiki.md) | Scaffolding prompt for Karpathy LLM Wiki architecture in any repository. |
+
+---
+
+## Environment Variables & Exit Codes
+
+### Environment Variables
+- `RNEX_CONFIG`: Overrides the default `rnex.yaml` configuration file path.
+- `NO_COLOR`: Disables ANSI color output when set.
+
+### Exit Codes
+- `0`: Success.
+- `1`: General error (e.g. invalid arguments, missing workspace configuration, command failure).

package/docs/rnex.example.yaml

@@ -12,6 +12,14 @@
 #
 # For more information: https://github.com/nu-nenoi/repo-nexus
 
+# ------------------------------------------------------------------------------
+# version — Workspace configuration schema version
+# ------------------------------------------------------------------------------
+# Used by `rnex fix` and `rnex update` to safely detect and reconcile configuration
+# and routing instructions across CLI releases.
+#
+version: 0.5.0
+
 # ------------------------------------------------------------------------------
 # repos_dir — Directory for member repository clones
 # ------------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-nexus",
-  "version": "0.4.7",
+  "version": "0.5.2",
   "description": "Lightweight, zero-dependency Virtual Meta-Repo companion for multi-repo workspaces and shared AI context (no git submodules)",
   "bin": {
     "repo-nexus": "rnex",
@@ -13,6 +13,7 @@
   "files": [
     "rnex",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "docs/",
     "toolkit/"
@@ -26,8 +27,6 @@
   },
   "homepage": "https://github.com/nu-nenoi/repo-nexus#readme",
   "keywords": [
-    "rnex",
-    "repo-nexus",
     "rnex",
     "repo-nexus",
     "multi-repo",
@@ -36,10 +35,6 @@
     "agents.md",
     "cursor-rules",
     "claude-code",
-    "ai-agents",
-    "agents.md",
-    "cursor-rules",
-    "claude-code",
     "copilot",
     "cursor",
     "plugins",