repo-nexus 0.6.16 → 0.7.0

package/CHANGELOG.md

@@ -7,28 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Changed
-- **Replaced `rnex fix` with `rnex sync` (with optional `--fix` flag)**:
-  - `rnex sync` without `--fix` performs a dry-run audit, checking workspace configuration, `.gitignore`, `.ignore`, AI routing instructions (`AGENTS.md`, provider files), active/disabled plugin assets, member repository scaffolding, and multi-root workspace definitions, logging any inconsistencies without mutating files.
-  - `rnex sync --fix` (or `-f`) executes full workspace reconciliation, schema upgrades, prompt/workflow synchronization, and asset repairs.
-  - `rnex fix` is maintained as a deprecated backward-compatible alias for `rnex sync --fix`, displaying a deprecation notice directing users to `rnex sync --fix`.
-  - All workspace documentation, guides, prompt templates, and AI routing instructions updated to reference `rnex sync` and `rnex sync --fix`.
+## [0.6.16] - 2026-10-14
+
+### Removed
+- **`rnex fix` and `rnex status --fix`**: Removed in favor of `rnex sync` as the sole reconciliation command.
+- **Legacy Sample Instructions**: Removed `docs/AGENTS.sample.md` and replaced it with `docs/ai-instructions.sample.md` (and root `templates/ai-instructions.sample.md`).
+- **Core Plugin Decoupling**: Removed all hardcoded plugin references from `./rnex` core so the CLI is strictly plugin-agnostic.
 
 ### Added
-- **Modular Test Suite Architecture**:
-  - Decomposed monolithic `tests/test_cli.sh` (996 lines, 36 tests) into modular, single-responsibility test suites under `tests/suites/`:
-    - `01_core_cli.sh`: Workspace initialization, member repository lifecycle (`add`, `exec`, `enable`, `disable`, `clone`, `remove`), version inspection, and shell completion generators.
-    - `02_plugins_basic.sh`: Plugin discovery, inspection, activation, scoping under `.rnex/plugins/`, and delimited `AGENTS.md` routing.
-    - `03_config_workspace.sh`: Two-level configuration (`.local.rnex.yaml`), Git ignore reconciliation, status reporting, multi-root workspace generation, version-aware upgrade engine, and standardized skills/workflows synchronization.
-    - `04_git_hooks.sh`: Automated Git hooks installation, runtime status, workspace-level `git_hooks` configuration, execution dispatch, custom wrapper preservation, and repository `.githooks/` chaining.
-    - `05_ai_providers.sh`: AI provider plugins synchronization and surgical non-destructive cleanup across Copilot, Claude, Gemini, Cursor, and Windsurf.
-    - `06_plugins_advanced.sh`: Deterministic plugin updates, Karpathy LLM Wiki configurable paths (`wiki_dir`, `raw_dir`), and complete plugin deactivation with prompt cleanup.
-  - Shared test harness `tests/test_helper.sh` provides dynamic repository root resolution, isolated workspace scaffolding, standardized assertion helpers (`run_test`, `pass`, `fail`), and standalone execution detection.
-  - Backward-compatible runner `tests/test_cli.sh` executes all 36 tests sequentially and supports running individual suites by name or numeric prefix (e.g. `./tests/test_cli.sh 06`).
-- **Standardized Root `templates/` Directory**:
-  - Moved reference configuration and instruction templates ([`rnex.example.yaml`](file:///Users/admin/Projects/ai/repo-nexus/templates/rnex.example.yaml) and [`AGENTS.sample.md`](file:///Users/admin/Projects/ai/repo-nexus/templates/AGENTS.sample.md)) from `docs/` to root [`templates/`](file:///Users/admin/Projects/ai/repo-nexus/templates/).
-  - Pruned empty placeholder directory `toolkit/templates/`.
-  - Updated config pointers in [`rnex.yaml`](file:///Users/admin/Projects/ai/repo-nexus/rnex.yaml) and [`init.sh`](file:///Users/admin/Projects/ai/repo-nexus/lib/commands/init.sh), package distribution in [`package.json`](file:///Users/admin/Projects/ai/repo-nexus/package.json), and cleaned up VitePress exclusions in [`docs/.vitepress/config.mts`](file:///Users/admin/Projects/ai/repo-nexus/docs/.vitepress/config.mts).
+- **Plugin Lifecycle Hooks & Contract**: Added `before_<cmd>` and `after_<cmd>` hook execution across all mutating commands (`init`, `install`, `add`, `clone`, `exec`, `remove`, `enable`, `disable`, `rnex-dir`, `sync`, `update`, `hooks`, `plugin`) while bypassing read-only commands (`status`, `list`, `completion`).
+- **Compiled AI Instructions (`.rnex/ai-instructions.md`)**: `rnex sync` now compiles a unified instruction file inside `.rnex/` from the merged 2-level config (`rnex.yaml` + `.local.rnex.yaml`), base AI instructions template, and active plugin fragments.
+- **Event-Driven Auto-Sync**: Added checksum-based config drift detection (`.rnex/.sync_stamp`) that automatically runs `rnex sync --quiet` on any `rnex` CLI command or new AI session start without background file watchers. Includes shell prompt hook (`_rnex_auto_sync`) in `rnex completion` and Git hooks (`post-merge`, `post-checkout`, `pre-commit`).
+- **Contribution Guide**: Added `CONTRIBUTION.md` documenting POSIX shell standards, plugin contract rules, and test workflows.
+- **Modular Test Suite Architecture**: Decomposed monolithic test runner into modular test suites under `tests/suites/` (`01_core_cli.sh` through `06_plugins_advanced.sh`) with shared harness `tests/test_helper.sh`.
+- **Maintainer Release Hooks Relocation**: Relocated maintainer Git hooks from `.githooks/` into `scripts/githooks/` to ensure workspace root strictly encapsulates internal state in `.rnex/`.
+
+### Changed
+- **`rnex sync` Scope**: Synchronizes `rnex-*` prompts from `toolkit/prompts/` and `.rnex/` directories in both the nexus root and enabled member repositories (`repos/<name>/.rnex/`).
+- **Root AI Provider Files (`AGENTS.md`, `CLAUDE.md`)**: Simplified to contain only a single strict directive instructing agents to read and follow `.rnex/ai-instructions.md`.
+- **`karpathy-llm` Plugin Defaults & Hooks**: Migrated `karpathy-llm` to lifecycle hooks and changed default paths from `/wiki/` to `.rnex/wiki` (curated knowledge base) and from `/raw/` to `./docs` (raw intake).
+
+### Fixed
+- Unified GitHub repository URLs across `README.md`, `scripts/install.sh`, and the documentation site to canonical `unoxen/repo-nexus`.
+- Removed legacy `symlinks` references from repository metadata.
+
 
 ## [0.6.7] - 2026-10-12
 

package/README.md

@@ -14,7 +14,7 @@ A **simple, lightweight Virtual Meta-Repo companion** for multi-repo workspaces
 - **Two-Level Configuration as Source of Truth**: Shared team manifest in `rnex.yaml` with machine-specific overrides in `.local.rnex.yaml` (highest priority).
 - **One Command Team Onboarding**: Teammates clone the meta-repo and run `rnex clone` to clone and configure all member repos in seconds.
 - **Cross-Repo Batch Operations**: Run arbitrary commands across all active repositories with `rnex exec <command>`.
-- **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`).
+- **Scoped Plugins & Context Packs**: Modular plugin packages scoped under `.rnex/plugins/<plugin-name>/` with support for domain directories (e.g. `.rnex/wiki` and `./docs` for `karpathy-llm`).
 - **Zero Dependencies**: Pure POSIX shell CLI (`rnex`). Works out of the box across macOS, Linux, and Windows (WSL/Git Bash).
 
 > 📖 **Documentation & Guides**
@@ -38,6 +38,7 @@ A **simple, lightweight Virtual Meta-Repo companion** for multi-repo workspaces
 - [Quick Start](#quick-start)
 - [Project Structure](#project-structure)
 - [Running Tests](#running-tests)
+- [Contributing](#contributing)
 - [License](#license)
 
 ---
@@ -137,8 +138,9 @@ repo-nexus/
 ├── rnex                            # CLI executable (POSIX shell)
 ├── AGENTS.md                       # Routing-only universal AI instructions
 ├── CHANGELOG.md                    # Release history and migration notes
+├── CONTRIBUTION.md                 # POSIX standards, testing setup, and plugin contract
 ├── templates/
-│   ├── AGENTS.sample.md            # Template for routing-only AGENTS.md
+│   ├── ai-instructions.sample.md   # Base template for .rnex/ai-instructions.md
 │   └── rnex.example.yaml           # Full config reference with examples
 ├── docs/
 │   ├── guide/                      # Architecture, workflows, and getting started
@@ -148,6 +150,9 @@ repo-nexus/
 │   └── faq/                        # Frequently Asked Questions
 ├── .github/
 │   └── workflows/ci.yml            # GitHub Actions CI workflow
+├── scripts/
+│   ├── install.sh                  # Zero-dependency standalone installer
+│   └── githooks/                   # Repository maintainer release hooks
 ├── tests/
 │   ├── test_cli.sh                 # Main test runner
 │   ├── test_helper.sh              # Shared test harness and utilities
@@ -170,6 +175,12 @@ repo-nexus/
 
 ---
 
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTION.md](CONTRIBUTION.md) for coding standards (pure POSIX shell, ShellCheck compliance), local development & maintainer Git hooks setup, automated test workflows, and plugin authoring guidelines.
+
+---
+
 ## License
 
 [MIT](LICENSE)

package/docs/CLI.md

@@ -0,0 +1,93 @@
+# Repo Nexus (`rnex`) — Command Line Interface Reference
+
+Lightweight zero-dependency Virtual Meta-Repo companion for multi-repo workspaces and shared AI context.
+
+## Core Commands
+
+| Command | Syntax | Description |
+|:---|:---|:---|
+| `init` | `rnex init [-y] [--claude] [--copilot] [--gemini] [--cursor] [--windsurf] [--code-workspace]` | Initialize a new workspace, create `rnex.yaml`, `.rnex/`, `.ignore`, and minimal AI instructions. |
+| `sync` | `rnex sync [-y] [--quiet]` | **Single reconciliation command**: syncs prompts, `.rnex/` harness, plugins, and compiles `.rnex/ai-instructions.md`. |
+| `status` | `rnex status` | **Strictly read-only**: inspect workspace health, active repos, loaded config, git hooks, sync stamp, and plugins. |
+| `add` | `rnex add <name> <git-url> [--local]` | Register a new member repository and clone into `./repos/<name>`. |
+| `clone` | `rnex clone` | Clone all declared member repositories missing from disk. |
+| `exec` | `rnex exec <command>` | Run an arbitrary shell command across all active member repositories. |
+| `list` | `rnex list` | List all member repositories and their active status. |
+| `enable` | `rnex enable <name> [--local]` | Enable a member repository in active workspace. |
+| `disable` | `rnex disable <name> [--local]` | Disable a member repository in active workspace. |
+| `remove` | `rnex remove <name> [-y]` | Unregister repository and remove its clone from disk. |
+| `rnex-dir`| `rnex rnex-dir <enable\|disable> <name>` | Toggle `.rnex/` harness inside a member repository. |
+| `update` | `rnex update [-y] [--quiet]` | Check configuration version and upgrade to latest schema (delegates to `sync`). |
+| `hooks` | `rnex hooks <install\|uninstall\|status>` | Manage automated workspace Git hooks. |
+| `plugin` | `rnex plugin <list\|info\|enable\|disable\|update>` | Manage workspace plugins. |
+| `completion` | `rnex completion <bash\|zsh\|fish>` | Generate shell completions with event-driven auto-sync hooks. |
+
+---
+
+## Reconciliation Command: `rnex sync`
+
+`rnex sync` is the sole reconciliation command (`rnex fix` and `rnex status --fix` have been removed).
+
+```bash
+rnex sync [-y|--yes] [-q|--quiet]
+```
+
+### Reconciliation Actions
+1. **Config Version Upgrade**: Detects schema drift and non-destructively upgrades `rnex.yaml` if older than the installed CLI version.
+2. **Git Ignore & Search Indexing**: Reconciles `.gitignore` (ignoring `repos/*` and `.local.rnex.yaml`) and `.ignore` (un-ignoring `repos/*` for search tools).
+3. **Plugin Sync**: Prunes disabled plugins and deterministically copies enabled plugin assets, rules, workflows, templates, and executable lifecycle hooks into `.rnex/plugins/<plugin-name>/`.
+4. **Compiled AI Instructions**: Compiles `.rnex/ai-instructions.md` by combining the base template with active configuration and all enabled plugin `instructions.md` fragments. Top-level provider files (`AGENTS.md`, `CLAUDE.md`, etc.) receive only a single strict directive pointing to `.rnex/ai-instructions.md`.
+5. **Prompt Sync**: Copies all operational prompts matching `rnex-*` from `toolkit/prompts/` into configured AI assistant directories (Claude, Gemini, Cursor, Windsurf, Copilot) and workspace prompt directories.
+6. **Harness Sync**: Reconciles root `.rnex/` and member repository harnesses (`repos/<name>/.rnex/`) for all enabled member repositories where `rnex_dir: true`.
+7. **Git Hooks**: Installs or reconciles workspace Git hooks in `.rnex/hooks` when `git_hooks: true`.
+8. **Multi-Root Workspace**: Synchronizes `.code-workspace` folder mappings when `code_workspace: true`.
+9. **Event-Driven Auto-Sync Scripts & Stamp**: Generates `.rnex/bin/auto-sync.sh` and updates `.rnex/.sync_stamp`.
+
+---
+
+## Plugin Contract & Lifecycle Hooks
+
+Repo Nexus core is 100% agnostic of specific plugins. All mutating commands dispatch lifecycle hooks before and after execution.
+
+### Action Command Hook Dispatcher
+All state-changing commands (`init`, `add`, `clone`, `exec`, `remove`, `enable`, `disable`, `rnex-dir`, `sync`, `update`, `hooks`, `plugin`) trigger:
+- `before_<cmd>` hook
+- `after_<cmd>` hook
+
+Read-only commands (`status`, `list`, `completion`, `--help`, `--version`) bypass lifecycle hooks.
+
+### Plugin Manifest & File Layout
+Plugins are authored in `toolkit/plugins/<plugin-name>/` and synced into `.rnex/plugins/<plugin-name>/`:
+
+```text
+toolkit/plugins/<plugin-name>/
+├── plugin.yaml                  # Manifest (name, version, description, default config)
+├── instructions.md              # Optional AI instruction fragment merged during rnex sync
+├── hooks/                       # POSIX /bin/sh hook scripts (chmod +x)
+│   ├── after_sync.sh            # Executes after workspace reconciliation
+│   ├── after_init.sh            # Executes after workspace initialization
+│   └── before_remove.sh         # Executes before member repo removal
+├── rules/                       # AI assistant behavioral rules
+├── workflows/                   # Standardized agent workflow procedures
+└── templates/                   # Default files and scaffold templates
+```
+
+### Environment Context Passed to Hooks
+Every lifecycle hook receives the following environment variables:
+
+| Variable | Description |
+|:---|:---|
+| `RNEX_ROOT` | Absolute path to the Repo Nexus workspace root directory. |
+| `RNEX_CONFIG_MERGED` | Path to the active workspace configuration (`rnex.yaml`). |
+| `RNEX_PLUGIN_DIR` | Path to the scoped plugin directory (`.rnex/plugins/<plugin-name>`). |
+| `RNEX_CMD` | The command being executed (e.g., `sync`, `init`, `add`). |
+| `RNEX_ARGS` | Arguments passed to the command. |
+| `RNEX_QUIET` | Set to `1` when `--quiet` was passed, `0` otherwise. |
+
+### Karpathy LLM Wiki Plugin
+The `karpathy-llm` plugin uses lifecycle hooks to manage its domain directories:
+- **Default curated knowledge base (`wiki_dir`)**: `.rnex/wiki`
+- **Default append-only raw intake (`raw_dir`)**: `./docs`
+- **Master navigation index**: `.rnex/wiki/index.md`
+- **Rolling orientation cache**: `.rnex/wiki/hot.md`
+- **Operation log**: `.rnex/wiki/_log.md`

package/docs/FAQ.md

@@ -0,0 +1,180 @@
+---
+title: Frequently Asked Questions
+description: Comprehensive FAQ for Repo Nexus, covering architecture, Git internals, submodule pitfalls, two-level config, AI context routing, and system requirements.
+---
+
+# Frequently Asked Questions (FAQ)
+
+This document answers common architectural, operational, and technical questions about **Repo Nexus (`rnex`)**, why it exists, how it works as a **Virtual Meta-Repo for AI Agents**, how it handles Git autonomy, and how to use it effectively.
+
+---
+
+## General Setup & Philosophy
+
+### What is repo-nexus?
+
+It is a zero-dependency **Virtual Meta-Repo companion** that organizes multiple independent Git repositories into a unified development workspace with shared AI routing context.
+
+---
+
+### How does it differ from traditional monorepo orchestrators?
+
+Unlike heavy monorepo tools (such as Nx, Turborepo, or Bazel) that take over build pipelines, require unified lockfiles, and impose cross-package dependency graphs, `repo-nexus` acts strictly as an architectural companion. It does not replace your compiler, test runner, package manager, or build tooling.
+
+---
+
+### Does it require Git Submodules?
+
+**No.** Member repositories are physically cloned into `./repos/<name>`. The workspace root `.gitignore` strictly ignores `repos/`. Each repository remains a 100% normal, autonomous Git repository with its own `.git` directory, remotes, branches, and commit history. There are no `.gitmodules`, no detached HEADs, and no submodule pointer commits.
+
+---
+
+### Why do I need rnex?
+
+Modern AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, Antigravity) are designed around a single project root. In real-world software development, applications are rarely confined to a single repository—they are split across frontends, backend APIs, shared packages, and infrastructure.
+
+This creates two major frictions:
+1. **Siloed Context**: Opening one repository in an AI tool leaves the AI blind to API contracts, types, or services in other repositories, leading to hallucinations.
+2. **Onboarding Friction**: New team members must manually find and clone 5–10 repos, set up local folder structures, and configure tools.
+
+**`rnex` solves both**:
+- It unites repositories under one Virtual Meta-Repo root so AI assistants see the whole stack.
+- It enables 1-command onboarding: teammates run `rnex clone` and every repository is cloned and wired up in seconds.
+
+---
+
+### Why not just use a monorepo or Git submodules?
+
+| Solution | Drawbacks | How `rnex` compares |
+| :--- | :--- | :--- |
+| **Git Monorepo** | Heavy migration effort, combined CI/CD pipelines, complex permissions, slow checkouts. | **Zero migration**: Repositories remain completely independent with their own remotes and CI/CD pipelines. |
+| **Git Submodules** | Detached HEAD states, tricky merge conflicts, complex multi-step commits, rigid coupling. | **Zero submodule friction**: Root Git ignores `repos/`. Repos are completely normal autonomous clones. |
+| **Manual Multi-Window** | Juggling 5 IDE windows, copy-pasting API types, fragmented AI reasoning. | **Unified Workspace**: AI agents see the entire system from the meta-repo root. |
+
+---
+
+## Architecture & Mechanics
+
+### How does the Virtual Meta-Repo work?
+
+When you initialize a workspace (`rnex init`), `rnex` creates:
+1. `rnex.yaml` (declaring member repository URLs and active plugins).
+2. Root `.gitignore` (ignoring `repos/` and `.local.rnex.yaml`).
+3. Routing-only `AGENTS.md` (directing AI assistants to configuration and plugins).
+4. `.rnex/` (strictly encapsulating all internal rnex assets and scoped plugins).
+
+When you run `rnex add <name> <git-url>` or `rnex clone`, member repositories are cloned directly into `./repos/<name>`.
+
+---
+
+### Why use physical clones in `./repos/` instead of symlinks?
+
+1. **Universal Portability**: Zero symlink fragility. Works 100% natively on macOS, Linux, and Windows without elevated permissions or Developer Mode.
+2. **File Watcher & Tool Compatibility**: Native folders avoid known symlink bugs in IDE file watchers, bundlers, and linters.
+3. **Intuitive Simplicity**: Every project is right where you expect it in `./repos/<name>`.
+
+---
+
+### Can I use Git commands (pull, push, commit) on member repos?
+
+**Yes.** Git operates completely normally.
+When you or your IDE navigate into `repos/<name>/` and run `git status`, `git commit`, `git pull`, or `git push`, Git operates directly against that repository's own branches and remotes.
+
+---
+
+### Can AI agents create and modify files inside member repos?
+
+**Yes.** Any file created or modified under `repos/<name>/...` (e.g. `repos/backend/src/api.ts`) is a real file inside that repository, immediately tracked by that repo's Git.
+
+---
+
+### Will rnex interfere with Git branches, remotes, or commit histories?
+
+**No.** The workspace root `.gitignore` ignores `repos/`. The workspace Git repository never commits or interferes with member repository contents.
+
+---
+
+### How does batch execution (rnex exec) work?
+
+Running `rnex exec <command>` iterates through every active, enabled repository in `./repos/` and executes the command within that directory. For example:
+
+```bash
+rnex exec git status -s
+rnex exec npm test
+```
+
+---
+
+## Configuration & AI Context Routing
+
+### What is the two-level configuration model?
+
+1. **Repo Config (`rnex.yaml`)**: Shared team manifest committed to Git. Declares repo URLs, default enabled states, and plugins.
+2. **Local Config (`.local.rnex.yaml`)**: Machine-specific file ignored by Git. Takes **highest priority** and overrides repo settings.
+
+---
+
+### How does the enabled/disabled setting work?
+
+Repositories support an `enabled: true|false` setting:
+- **Default State**: Enabled (`true`). If omitted, the repository is automatically considered enabled.
+- **Local Overrides**: If a team has 10 repos, but a developer only works on two, they can set `enabled: false` for the other eight in `.local.rnex.yaml`.
+- **Disabled Repositories**: Skipped by `rnex clone`, `rnex exec`, and excluded from AI agent tasks.
+
+CLI commands:
+```bash
+rnex disable analytics --local    # disable locally
+rnex enable analytics             # re-enable
+```
+
+---
+
+### What is the routing-only instructions pattern in AGENTS.md?
+
+Top-level AI instructions (`AGENTS.md`, `CLAUDE.md`, etc.) do not include sprawling inlined rules or tool text. Instead, they act as **lean navigation routers**:
+1. Mandate reading `.local.rnex.yaml` (highest priority) and `rnex.yaml` first.
+2. Route agents to `.rnex/plugins/<plugin-name>/` for scoped plugin rules.
+3. Route agents to `repos/<name>/.rnex/` for member-specific instructions.
+
+---
+
+### What is the member repository `.rnex/` directory?
+
+Repo Nexus initializes an isolated `.rnex/` folder inside each member repository (`repos/<name>/.rnex/`):
+- Encapsulates Repo Nexus metadata and scoped plugin rules for that repository.
+- Keeps member repository roots clean and untouched.
+- Can be disabled at any time with `rnex rnex-dir disable <name>`.
+
+---
+
+### How are plugins structured and scoped?
+
+Plugins are strictly scoped under `.rnex/plugins/<plugin-name>/`.
+For example, the built-in `karpathy-llm` plugin places its rules, workflows, and instructions in `.rnex/plugins/karpathy-llm/`, while instantiating domain directories (`./docs` for intake documents and `.rnex/wiki` for curated knowledge) as specified by its architecture.
+
+---
+
+## Platforms & Setup
+
+### What are the system requirements? Does it work on Windows?
+
+`rnex` is written in POSIX shell script (`/bin/sh`). It runs natively on:
+- **macOS**
+- **Linux**
+- **Windows** (via WSL2, Git Bash, or MSYS2)
+
+Because `rnex` uses standard physical folders and `git clone` instead of symlinks, it has zero symlink permission limitations on Windows.
+
+---
+
+### Does rnex have external runtime dependencies?
+
+**No.** The `rnex` executable has zero external dependencies—no Node.js runtime, Python, or external package managers are required to execute the CLI.
+
+---
+
+### What files should be committed to Git?
+
+In your Repo Nexus workspace Git repository:
+- **Commit**: `rnex.yaml`, `AGENTS.md`, `docs/`, `toolkit/`, and `.gitignore`.
+- **Do NOT Commit**: `repos/` and `.local.rnex.yaml` (both are strictly ignored by `.gitignore`).

package/docs/ai-instructions.sample.md

@@ -0,0 +1,25 @@
+# Multi-Repo AI Workspace Context
+
+This workspace operates as a **Repo Nexus Virtual Meta-Repo** uniting independent repositories.
+
+## Routing Protocol for AI Assistants
+
+### Mandatory Session Startup
+Execute in sequence before task execution:
+1. **Read Configuration First (Highest Priority)**: Read `.local.rnex.yaml` (if present) and `rnex.yaml` to identify active member repositories (`repos/`) and enabled plugins.
+2. **Plugin & Skill Routing**: Inspect active plugin instructions under `.rnex/plugins/<plugin-name>/`, and tools under `.rnex/skills/` and `.rnex/workflows/` when relevant.
+3. **Targeted Member Repository Access Only**: Navigate directly to specific files in `repos/<name>/` relevant to the user request. Avoid blind repository-wide scans or unbounded searches across `repos/`.
+
+## Subagents
+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.
+
+## Workspace Maintenance
+When workspace configuration, routing blocks, plugin assets, or member repository structures require reconciliation or schema upgrades:
+- Run `rnex sync` (or `rnex status` to check workspace health).
+- 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>/`).

package/docs/cli/index.md

@@ -12,9 +12,9 @@ description: Fast reference cheatsheet for rnex commands, global options, enviro
 | Command | Category | Description |
 |:---|:---|:---|
 | [`rnex init`](workspace.md#rnex-init) | Workspace | Initialize a new Repo Nexus workspace. |
-| [`rnex status`](workspace.md#rnex-status) | Workspace | Inspect workspace health, clones, and AI instructions. |
-| [`rnex sync`](workspace.md#rnex-sync) | Workspace | Check workspace consistency, or reconcile with `--fix`. |
-| [`rnex update` / `upgrade`](workspace.md#rnex-update-alias-upgrade) | Workspace | Part of sync --fix: verify version, upgrade schema, and reconcile workspace. |
+| [`rnex sync`](workspace.md#rnex-sync) | Workspace | Single reconciliation command: sync prompts, .rnex/ harness, and compile AI instructions. |
+| [`rnex status`](workspace.md#rnex-status) | Workspace | Strictly read-only: inspect workspace health, active repos, loaded config, and plugins. |
+| [`rnex update` / `upgrade`](workspace.md#rnex-update-alias-upgrade) | Workspace | Check configuration version and upgrade schema (delegates to `rnex sync`). |
 | [`rnex install`](workspace.md#rnex-install) | Workspace | Symlink `rnex` to `~/.local/bin`. |
 | [`rnex completion`](workspace.md#rnex-completion) | Workspace | Generate shell auto-completion for Zsh, Bash, or Fish. |
 | [`rnex version`](workspace.md#rnex-version) | Workspace | Display current installed CLI version. |
@@ -49,7 +49,7 @@ rnex [global-options] <command> [command-options] [arguments]
 
 ## Standardized Prompts Catalog
 
-Repo Nexus provides a standardized suite of operational prompt templates in `toolkit/prompts/` that sync to `.rnex/prompts/` during `rnex sync --fix` or `rnex init`.
+Repo Nexus provides a standardized suite of operational prompt templates in `toolkit/prompts/` that sync during `rnex sync` or `rnex init`.
 
 AI assistants navigate workflows via the catalog index at `.rnex/prompts/index.md`:
 

package/docs/cli/tooling.md

@@ -21,9 +21,10 @@ rnex hooks install [--local]
 ```
 
 #### Installed Hooks:
-* **`post-merge`**: Runs `rnex sync --fix -y --quiet` automatically whenever `git pull` or upstream merges occur, ensuring newly added repositories and plugin updates sync instantly.
+* **`post-merge`**: Runs `rnex sync -y --quiet` automatically whenever `git pull` or upstream merges change `rnex.yaml`, ensuring newly added repositories and plugin updates sync instantly.
+* **`post-checkout`**: Runs `rnex sync -y --quiet` automatically whenever `rnex.yaml` changes across branch checkouts.
 * **`post-commit`**: Alerts the user if documentation or wiki files were committed without running maintenance linters.
-* **`pre-commit`**: Runs pre-commit validation triggers declared by active plugins.
+* **`pre-commit`**: Runs `rnex sync -y --quiet` when configuration files are staged, and triggers plugin validation.
 * **`pre-push`**: Runs pre-push validation triggers before pushing to remote.
 
 ### `rnex hooks status`

package/docs/cli/workspace.md

@@ -47,35 +47,9 @@ rnex init -y --claude --hooks
 
 Performs comprehensive diagnostic and health checks across the workspace.
 
-### Syntax
-```sh
-rnex status
-```
-
-### What It Reports
-* **Configuration State**: Location and schema version of `rnex.yaml` and `.local.rnex.yaml`.
-* **Git Status**: Validation that `.gitignore` ignores `repos/` and local files, and whether `core.hooksPath` points to `.rnex/hooks`.
-* **AI Routing**: Status of universal `AGENTS.md`, `.rnex/skills/`, `.rnex/workflows/`, and provider prompts directories.
-* **Member Clones**: Health, branches, and `.rnex` state of every member repository.
-
-```bash
-rnex status
-```
-
-```text
-[rnex] Workspace root: /workspace
-[rnex] Config: rnex.yaml (.local.rnex.yaml loaded)
-[rnex] Repositories: 2 active, 0 disabled
-```
-
----
-
 ## `rnex sync`
 
-Synchronizes workspace assets, validates configuration, and audits or reconciles AI routing instructions, skills, workflows, active plugins, and member clones.
-
-- **Audit Mode (Default)**: When run without `--fix`, inspects workspace configuration, Git ignores, routing blocks, plugin assets, and member repositories, logging any issues or inconsistencies without mutating files.
-- **Reconcile Mode (`--fix`)**: Reconciles configuration schema, updates instruction files, synchronizes skills/workflows, mirrors operational prompts, and fixes inconsistencies.
+Reconciles workspace configuration, prompts, plugins, `.rnex/` harness directories, and compiles `.rnex/ai-instructions.md`. `rnex sync` is the sole reconciliation command in Repo Nexus (`rnex fix` and `rnex status --fix` are removed).
 
 ### Syntax
 ```sh
@@ -85,27 +59,41 @@ rnex sync [options]
 ### Options
 | Option | Shorthand | Type | Default | Description |
 |:---|:---|:---|:---|:---|
-| `--fix` | `-f` | boolean | `false` | Apply reconciliation fixes across workspace, routing, plugins, and repos. |
-| `--yes` | `-y` | boolean | `false` | Automatically confirm schema upgrades if prompted (used with `--fix`). |
+| `--yes` | `-y` | boolean | `false` | Automatically confirm schema upgrades if prompted. |
 | `--quiet` | `-q` | boolean | `false` | Quiet mode; suppresses non-error informational messages (ideal for hooks). |
-| `--upgrade` | | boolean | `false` | Explicitly trigger version upgrade reconciliation (implies `--fix`). |
 
-### Reconciliation Actions (with `--fix`)
+### Reconciliation Actions
 1. Upgrades configuration schema non-destructively if an older version is detected.
 2. Re-verifies `.gitignore` rules for `repos/` and local configs, and ensures `.ignore` contains `!repos/*`.
-3. Inserts or updates delimited routing blocks in universal `AGENTS.md` and active provider instruction files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`).
-4. Syncs base workflows to `.rnex/workflows/` and base skills to `.rnex/skills/`, purging any legacy `.rnex/prompts/`.
-5. Mirrors operational prompts to enabled AI providers (`.github/prompts/`, `.claude/commands/`, etc.).
-6. Re-syncs enabled plugin assets into `.rnex/plugins/` and member `repos/<name>/.rnex/`.
+3. Compiles `.rnex/ai-instructions.md` by combining the base template with active configuration and all enabled plugin `instructions.md` fragments. Writes single strict directive to top-level provider files (`AGENTS.md`, `CLAUDE.md`, etc.).
+4. Syncs operational prompts matching `rnex-*` from `toolkit/prompts/` to workspace and configured AI assistant prompt directories.
+5. Re-syncs enabled plugin assets into `.rnex/plugins/` and member `repos/<name>/.rnex/`.
+6. Dispatches plugin lifecycle hooks (`before_sync`, `after_sync`).
 7. Reconciles automated Git hooks in `.rnex/hooks/` against `git_hooks` config.
-8. Re-creates member `.rnex/` scaffolding in active repositories.
+8. Re-creates member `.rnex/` scaffolding in active repositories (`rnex_dir: true`).
 9. Updates multi-root `.code-workspace` folder mappings if configured.
+10. Generates `.rnex/bin/auto-sync.sh` and updates the checksum stamp in `.rnex/.sync_stamp`.
+
+---
+
+## `rnex status`
+
+Inspects workspace health and diagnostic information. `rnex status` is **strictly read-only** with no `--fix` flag.
+
+### Syntax
+```sh
+rnex status
+```
+
+### Execution
+* **Strictly Read-Only**: Inspects workspace health, active repos, loaded config files (`rnex.yaml` and `.local.rnex.yaml`), git hooks, and plugins.
+* **Sync Diagnostics**: Compares current config checksums against `.rnex/.sync_stamp` and suggests running `rnex sync` if configuration drift is detected.
 
 ---
 
 ## `rnex update` (alias: `upgrade`)
 
-Runs version verification and invokes the unified `rnex sync --fix` reconciliation engine to upgrade workspace configuration and routing instructions to match the installed CLI version.
+Runs version verification and invokes `rnex sync` to upgrade workspace configuration and routing instructions to match the installed CLI version.
 
 ### Syntax
 ```sh
@@ -120,9 +108,9 @@ rnex upgrade [options]
 | `--quiet` | `-q` | boolean | `false` | Suppress non-error informational messages. |
 
 ### Relationship with `rnex sync`
-`rnex update` is part of the `rnex sync` command family:
+`rnex update` delegates directly to `rnex sync`:
 * **Upfront Version Diagnostics**: Compares `version:` in `rnex.yaml` against the installed CLI version. If already matching, it reports that the workspace is up to date.
-* **Unified Reconciliation**: Delegates directly to `rnex sync --fix`, ensuring configuration schema upgrades, instruction updates (`AGENTS.md`, provider files), skills/workflows sync, and plugin reconciliation occur in a single, idempotent pass.
+* **Unified Reconciliation**: Delegates directly to `rnex sync`, ensuring configuration schema upgrades, instruction updates (`AGENTS.md`, `.rnex/ai-instructions.md`), prompts, and plugin reconciliation occur in a single, idempotent pass.
 * **Non-Destructive Migration**: Upgrades schema keys while preserving comments, indentation, and custom configurations.
 
 ---

package/docs/examples/local-overrides.md

@@ -39,10 +39,10 @@ plugins:
 
 ### Apply the Overrides
 
-Run `rnex sync --fix` to reconcile your local configuration:
+Run `rnex sync` to reconcile your local configuration:
 
 ```bash
-rnex sync --fix
+rnex sync
 ```
 
 ```text

package/docs/faq/index.md

@@ -150,7 +150,7 @@ Repo Nexus initializes an isolated `.rnex/` folder inside each member repository
 ### How are plugins structured and scoped?
 
 Plugins are strictly scoped under `.rnex/plugins/<plugin-name>/`.
-For example, the built-in `karpathy-llm` plugin places its rules, workflows, and instructions in `.rnex/plugins/karpathy-llm/`, while instantiating external functional directories (`raw/` for intake documents and `wiki/` for curated knowledge) as specified by its architecture.
+For example, the built-in `karpathy-llm` plugin places its rules, workflows, and instructions in `.rnex/plugins/karpathy-llm/`, while instantiating domain directories (`./docs` for intake documents and `.rnex/wiki` for curated knowledge) as specified by its architecture.
 
 ---
 

package/docs/guide/architecture.md

@@ -79,7 +79,7 @@ This workspace operates as a Repo Nexus Virtual Meta-Repo uniting independent re
 ```
 
 ::: tip Preserving Custom Instructions
-Any custom guidelines, rules, or documentation authored outside the `<!-- REPO-NEXUS:START -->` and `<!-- REPO-NEXUS:END -->` markers are strictly preserved during `rnex sync --fix` or plugin synchronization.
+Any custom guidelines, rules, or documentation authored outside the `<!-- REPO-NEXUS:START -->` and `<!-- REPO-NEXUS:END -->` markers are strictly preserved during `rnex sync` or plugin synchronization.
 :::
 
 ### 5. Multi-Root IDE Workspaces

package/docs/guide/configuration.md

@@ -90,7 +90,7 @@ plugins:
 | `version` | string | Current CLI version | Schema version compatibility check. |
 | `repos_dir` | string | `./repos` | Relative or absolute path where member repos are cloned. |
 | `code_workspace` | boolean \| string | `false` | Enables `.code-workspace` generation. Pass a string for custom filename. |
-| `git_hooks` | boolean | `true` | Configures `.rnex/hooks` as `core.hooksPath` during `rnex sync --fix`. |
+| `git_hooks` | boolean | `true` | Configures `.rnex/hooks` as `core.hooksPath` during `rnex sync`. |
 | `repos` | map | `{}` | Map of member repository specifications keyed by name. |
 | `plugins` | map | `{}` | Map of enabled plugins and their configuration options. |
 
@@ -124,9 +124,9 @@ plugins:
 After modifying configuration files directly, reconcile the workspace state:
 
 ```bash
-rnex sync --fix
+rnex sync
 ```
 
-::: tip Audit vs. Reconcile
-Running `rnex sync` without `--fix` audits the workspace and logs any detected configuration inconsistencies without modifying files. Adding `--fix` applies the reconciliation.
+::: tip Status & Auto-Sync
+Running `rnex status` inspects workspace health and checks if configuration is in sync with `.rnex/.sync_stamp`. Running `rnex sync` applies full reconciliation and updates the sync stamp. Workspace commands (like `rnex list`) also automatically trigger auto-sync whenever configuration changes.
 :::

package/docs/guide/workflows.md

@@ -66,7 +66,7 @@ If a command fails in any repository, `rnex exec` exits immediately with that co
 Repo Nexus includes an automated hook runner configured via `core.hooksPath = .rnex/hooks`.
 
 ### Core Automated Hooks
-1. **`post-merge`**: When you pull updates to the meta-repo (`git pull`), the hook automatically executes `rnex sync --fix` to:
+1. **`post-merge`**: When you pull updates to the meta-repo (`git pull`), the hook automatically executes `rnex sync -y --quiet` if `rnex.yaml` changed to:
    * Clone newly declared member repositories.
    * Update AI routing instructions (`AGENTS.md`, etc.).
    * Sync plugin changes.