repo-nexus 0.5.13 → 0.5.14

package/docs/CLI.md

@@ -385,7 +385,6 @@ AI assistants navigate workflows via the catalog index at `.rnex/prompts/index.m
 | [`rnex-workspace-audit.md`](../toolkit/prompts/rnex-workspace-audit.md) | Health, git dirty status, branch tracking, and configuration audit workflow. |
 | [`rnex-wiki-ingest.md`](../toolkit/prompts/rnex-wiki-ingest.md) | Autonomous ingestion of source docs from `/raw/` into Karpathy LLM Wiki pages. |
 | [`rnex-wiki-lint.md`](../toolkit/prompts/rnex-wiki-lint.md) | Link validation, backlink (`mentioned_in`) recalculation, and index rebuilding. |
-| [`rnex-setup-karpathy-wiki.md`](../toolkit/prompts/rnex-setup-karpathy-wiki.md) | Scaffolding prompt for Karpathy LLM Wiki architecture in any repository. |
 
 ---
 

package/docs/cli/execution.md

@@ -0,0 +1,81 @@
+---
+title: Batch Execution (rnex exec)
+description: Master sequential multi-repo task automation with rnex exec, argument escaping, and exit code bubbling.
+---
+
+# Batch Execution (`rnex exec`)
+
+`rnex exec` runs arbitrary shell commands sequentially across every active (enabled) member repository in `./repos/`.
+
+---
+
+## Syntax
+
+```sh
+rnex exec <command...>
+```
+
+Repo Nexus automatically navigates into each enabled repository directory (`./repos/<name>`), runs the command in a subshell, prefixes output with repository headings, and checks exit codes.
+
+---
+
+## Behavior & Execution Model
+
+### Sequential Execution
+Commands execute one repository at a time in the order declared in `rnex.yaml`. This ensures predictable output logs and avoids parallel resource contention during intensive builds or test suites.
+
+### Exit Code Bubbling
+If a command produces a non-zero exit code in any member repository:
+1. `rnex exec` immediately prints an error header highlighting the failed repository.
+2. Downstream repositories are aborted.
+3. `rnex exec` exits with the failed command's exit code (`exit 1` or specific error code).
+
+::: tip Continuous Execution
+To continue through repositories regardless of errors, chain with a shell fallback:
+```bash
+rnex exec sh -c "npm test || true"
+```
+:::
+
+---
+
+## Common Use Cases & Examples
+
+### 1. Multi-Repo Git Status
+
+Inspect working tree changes across all repositories:
+
+```bash
+rnex exec git status -s
+```
+
+```text
+=== [backend] ===
+ M src/routes.ts
+?? test/new-test.ts
+
+=== [frontend] ===
+On branch main (working tree clean)
+```
+
+### 2. Fast-Forward Pull Across Repositories
+
+Pull upstream changes cleanly:
+
+```bash
+rnex exec git pull --ff-only
+```
+
+### 3. Running Lints or Formatting
+
+```bash
+rnex exec npm run lint
+```
+
+### 4. Running Custom Shell Pipelines
+
+For commands involving pipes, redirects, or complex variables, invoke them inside `sh -c`:
+
+```bash
+rnex exec sh -c "git branch --show-current && git log -1 --oneline"
+```

package/docs/cli/index.md

@@ -0,0 +1,64 @@
+---
+title: CLI Overview & Cheatsheet
+description: Fast reference cheatsheet for rnex commands, global options, environment variables, and exit codes.
+---
+
+# CLI Overview & Cheatsheet
+
+`rnex` is a zero-dependency command-line utility built entirely in pure POSIX shell (`/bin/sh`). It orchestrates **Virtual Meta-Repo** workspaces, coordinates member repositories, automates Git workflows, and mirrors AI context.
+
+## Quick Command Cheatsheet
+
+| 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 fix` / `sync`](workspace.md#rnex-fix-alias-sync) | Workspace | Reconcile config, routing, prompts, and plugins. |
+| [`rnex update` / `upgrade`](workspace.md#rnex-update-alias-upgrade) | Workspace | Safely upgrade workspace schema to installed CLI version. |
+| [`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. |
+| [`rnex add`](repos.md#rnex-add) | Repositories | Register a git repository and clone it into `./repos/`. |
+| [`rnex clone`](repos.md#rnex-clone) | Repositories | Clone all declared repositories missing from disk. |
+| [`rnex list`](repos.md#rnex-list) | Repositories | Print table of registered member repositories. |
+| [`rnex enable`](repos.md#rnex-enable-rnex-disable) | Repositories | Enable a repository (include in sync and exec). |
+| [`rnex disable`](repos.md#rnex-enable-rnex-disable) | Repositories | Disable a repository (exclude from sync and exec). |
+| [`rnex remove`](repos.md#rnex-remove) | Repositories | Unregister repository and delete clone from disk. |
+| [`rnex rnex-dir`](repos.md#rnex-rnex-dir) | Repositories | Toggle `.rnex/` context inside member repository. |
+| [`rnex exec`](execution.md) | Execution | Run arbitrary shell commands across all active repos. |
+| [`rnex hooks`](tooling.md#git-hooks-automation) | Tooling | Manage automated Git hooks (`post-merge`, etc.). |
+| [`rnex plugin`](tooling.md#plugin-management) | Tooling | List, inspect, enable, and disable workspace plugins. |
+
+---
+
+## Global Syntax & Flags
+
+```sh
+rnex [global-options] <command> [command-options] [arguments]
+```
+
+### Global Options Table
+
+| Flag | Shorthand | Type | Description |
+|:---|:---|:---|:---|
+| `--config <file>` | `-c <file>` | string | Path to custom workspace configuration file (e.g. `/path/to/rnex.yaml`). Executes as if running from that file's directory. |
+| `--help` | `-h` | boolean | Display command usage and help summary. |
+| `--version` | `-v` | boolean | Output CLI version. |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|:---|:---|
+| `RNEX_CONFIG` | Overrides the default configuration file path (`rnex.yaml`). |
+| `NO_COLOR` | Disables ANSI color sequences in terminal output when set. |
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|:---|:---|
+| `0` | Success. |
+| `1` | General error (missing config, invalid arguments, or failing `rnex exec` command). |

package/docs/cli/repos.md

@@ -0,0 +1,129 @@
+---
+title: Member Repository Commands
+description: CLI reference for managing member repositories in Repo Nexus, including add, clone, list, enable, disable, remove, and rnex-dir.
+---
+
+# Member Repository Commands
+
+Member repository commands register, clone, toggle, and manage individual git repositories managed under `./repos/`.
+
+---
+
+## `rnex add`
+
+Registers a repository in configuration and immediately clones it into `./repos/<name>`.
+
+### Syntax
+```sh
+rnex add [options] <name> <git-url>
+```
+
+### Parameters & Options
+| Option | Type | Default | Description |
+|:---|:---|:---|:---|
+| `<name>` | string | *(required)* | Short identifier for repository (used as folder name in `./repos/`). |
+| `<git-url>` | string | *(required)* | Remote Git clone URL (SSH or HTTPS). |
+| `--local` | boolean | `false` | Registers repository in `.local.rnex.yaml` instead of team `rnex.yaml`. |
+| `--disabled` | boolean | `false` | Registers repository with `enabled: false` (skips immediate clone). |
+| `--no-rnex-dir` | boolean | `false` | Sets `rnex_dir: false`, leaving member repository completely untouched. |
+
+### Examples
+```bash
+# Register and clone a shared team service
+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 all registered, enabled repositories missing on disk.
+
+### Syntax
+```sh
+rnex clone
+```
+
+```bash
+rnex clone
+```
+
+```text
+[rnex] Cloning backend into ./repos/backend...
+Cloning into './repos/backend'...
+[rnex] All member repositories cloned successfully.
+```
+
+::: tip Ideal for Onboarding
+Teammates cloning the meta-repo run `rnex clone` to fetch all member repositories in a single command.
+:::
+
+---
+
+## `rnex list`
+
+Outputs a formatted table of all registered member repositories, their active branches, clone state, and `.rnex` directory status.
+
+### Syntax
+```sh
+rnex list
+```
+
+```text
+Name       Enabled  Cloned  Branch  rnex-dir  URL
+backend    yes      yes     main    yes       git@github.com:myorg/backend-api.git
+frontend   yes      yes     develop yes       git@github.com:myorg/frontend-web.git
+analytics  no       no      -       no        git@github.com:myorg/analytics.git
+```
+
+---
+
+## `rnex enable` & `rnex disable`
+
+Toggles whether a member repository is active in workspace operations.
+
+### Syntax
+```sh
+rnex enable [--local] <name>
+rnex disable [--local] <name>
+```
+
+* When disabled, a repository is excluded from `rnex clone`, `rnex exec`, and AI agent routing.
+* Pass `--local` to persist the toggle in `.local.rnex.yaml` without modifying team-wide `rnex.yaml`.
+
+```bash
+# Disable a memory-heavy service locally
+rnex disable --local monolith
+```
+
+---
+
+## `rnex remove`
+
+Unregisters a member repository from configuration and deletes its clone from `./repos/<name>`.
+
+### Syntax
+```sh
+rnex remove <name>
+```
+
+::: danger Destructive Operation
+`rnex remove` deletes the target repository folder from disk. Always ensure you have pushed any working branches or uncommitted changes to remote before confirming deletion.
+:::
+
+---
+
+## `rnex rnex-dir`
+
+Toggles member-level context projection inside `repos/<name>/.rnex/`.
+
+### Syntax
+```sh
+rnex rnex-dir <enable|disable> <name>
+```
+
+* When enabled, workspace prompts and plugin context are projected into `repos/<name>/.rnex/` for localized AI assistants.
+* When disabled, the repository root remains completely pristine.

package/docs/cli/tooling.md

@@ -0,0 +1,91 @@
+---
+title: Tooling & Git Hooks
+description: CLI reference for automated Git hooks management and modular plugin operations in Repo Nexus.
+---
+
+# Tooling & Git Hooks
+
+This section covers the `rnex hooks` and `rnex plugin` command suites used to configure workspace automations and modular integrations.
+
+---
+
+## Git Hooks Automation
+
+Repo Nexus configures workspace-level Git hooks using Git's native `core.hooksPath = .rnex/hooks`.
+
+### `rnex hooks install`
+Installs native hook scripts into `.rnex/hooks/` and sets `git_hooks: true` in configuration.
+
+```sh
+rnex hooks install [--local]
+```
+
+#### Installed Hooks:
+* **`post-merge`**: Runs `rnex fix -y --quiet` automatically whenever `git pull` or upstream merges occur, ensuring newly added repositories and plugin updates sync instantly.
+* **`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-push`**: Runs pre-push validation triggers before pushing to remote.
+
+### `rnex hooks status`
+Displays the active hooks configuration, current Git `core.hooksPath`, installed hook dispatchers, and active plugin triggers.
+
+```sh
+rnex hooks status
+```
+
+### `rnex hooks uninstall`
+Unsets `core.hooksPath`, removes `.rnex/hooks/`, and sets `git_hooks: false` in configuration.
+
+```sh
+rnex hooks uninstall [--local]
+```
+
+---
+
+## Plugin Management
+
+Plugins provide AI routing rules, standardized prompts, agent workflows, and shared context protocols.
+
+### `rnex plugin list`
+Displays all available plugins distributed with `rnex` and indicates whether they are enabled.
+
+```sh
+rnex plugin list
+```
+
+```text
+Plugin        Category          Status    Description
+claude        AI Provider       enabled   Anthropic Claude Code & Desktop
+copilot       AI Provider       disabled  GitHub Copilot workspace rules
+cursor        AI Provider       enabled   Cursor IDE rules & context
+gemini        AI Provider       disabled  Google Gemini & Antigravity
+karpathy-llm  Knowledge/Rules   enabled   Karpathy LLM 4 Cardinal Rules & Wiki
+windsurf      AI Provider       disabled  Windsurf IDE rules & context
+```
+
+### `rnex plugin info`
+Displays detailed metadata, configurable YAML options, and scoped assets for a specific plugin.
+
+```sh
+rnex plugin info <name>
+```
+
+```bash
+rnex plugin info claude
+```
+
+### `rnex plugin enable`
+Enables a plugin, creates `.rnex/plugins/<name>/`, and syncs mirrored assets.
+
+```sh
+rnex plugin enable [--local] <name>
+```
+
+* Pass `--local` to enable the plugin only in `.local.rnex.yaml` without changing team configuration.
+
+### `rnex plugin disable`
+Disables a plugin and cleans up its assets from `.rnex/plugins/<name>/`.
+
+```sh
+rnex plugin disable [--local] <name>
+```

package/docs/cli/workspace.md

@@ -0,0 +1,166 @@
+---
+title: Workspace Commands
+description: CLI reference for rnex workspace lifecycle commands including init, status, fix, sync, update, completion, and install.
+---
+
+# Workspace Commands
+
+Workspace commands manage the meta-repo configuration, AI routing files, health diagnostics, and environment integrations.
+
+---
+
+## `rnex init`
+
+Initializes a new Repo Nexus Virtual Meta-Repo workspace.
+
+### Syntax
+```sh
+rnex init [options] [directory]
+```
+
+### Parameters & Options
+| Option | Shorthand | Type | Default | Description |
+|:---|:---|:---|:---|:---|
+| `directory` | | string | `$PWD` | Target directory to initialize. |
+| `--yes` | `-y` | boolean | `false` | Non-interactive mode; accepts all defaults automatically. |
+| `--code-workspace` | | boolean \| string | `false` | Enable VS Code multi-root workspace file. Pass string for custom name. |
+| `--hooks` | | boolean | `true` (if git) | Force-enable automated Git hooks setup during initialization. |
+| `--no-hooks` | | boolean | `false` | Skip Git hooks configuration during initialization. |
+| `--claude` | | boolean | `false` | Enable Claude Code plugin (`CLAUDE.md` and `.claude/`). |
+| `--copilot` | | boolean | `false` | Enable GitHub Copilot plugin (`.github/`). |
+| `--cursor` | | boolean | `false` | Enable Cursor plugin (`.cursorrules` and `.cursor/rules/`). |
+| `--gemini` | | boolean | `false` | Enable Google Gemini plugin (`GEMINI.md` and `.gemini/`). |
+| `--windsurf` | | boolean | `false` | Enable Windsurf plugin (`.windsurfrules` and `.windsurf/`). |
+
+### Examples
+```bash
+# Interactive setup
+rnex init
+
+# Non-interactive initialization for CI or automated setup
+rnex init -y --claude --hooks
+```
+
+---
+
+## `rnex status`
+
+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**: Existence of delimited routing blocks in `AGENTS.md`, `CLAUDE.md`, etc.
+* **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 fix` (alias: `sync`)
+
+Reconciles workspace configuration, AI routing blocks, prompts catalog, active plugins, and member clones.
+
+### Syntax
+```sh
+rnex fix [options]
+rnex sync [options]
+```
+
+### Options
+| Option | Shorthand | Type | Default | Description |
+|:---|:---|:---|:---|:---|
+| `--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. |
+
+### Reconciliation Actions
+1. Upgrades configuration schema non-destructively if older version detected.
+2. Re-verifies `.gitignore` rules for `repos/` and local configs.
+3. Inserts or updates delimited routing blocks (`<!-- REPO-NEXUS:START -->` ... `<!-- REPO-NEXUS:END -->`).
+4. Syncs standardized workflow prompts into `.rnex/prompts/`.
+5. Re-syncs enabled plugin assets into `.rnex/plugins/` and member `repos/<name>/.rnex/`.
+
+---
+
+## `rnex update` (alias: `upgrade`)
+
+Safely updates an existing workspace's configuration schema and routing instructions to match the currently installed CLI version.
+
+### Syntax
+```sh
+rnex update [-y]
+rnex upgrade [-y]
+```
+
+* Upgrades configuration schema without wiping comments or indentation.
+* Reconciles AI instructions and active provider plugins in a single run.
+
+---
+
+## `rnex install`
+
+Symlinks the `rnex` and `repo-nexus` executables into a user or system bin directory.
+
+### Syntax
+```sh
+rnex install [bin-directory]
+```
+
+* Default target: `~/.local/bin`
+* Creates symlinks for both `rnex` and `repo-nexus`.
+
+---
+
+## `rnex completion`
+
+Generates shell auto-completion scripts.
+
+### Syntax
+```sh
+rnex completion <bash|zsh|fish>
+```
+
+::: code-group
+
+```sh [Zsh]
+# Add to ~/.zshrc
+source <(rnex completion zsh)
+```
+
+```sh [Bash]
+# Add to ~/.bashrc
+source <(rnex completion bash)
+```
+
+```sh [Fish]
+# Add to ~/.config/fish/config.fish
+rnex completion fish | source
+```
+
+:::
+
+---
+
+## `rnex version`
+
+Prints the installed version of `rnex`.
+
+```bash
+rnex version
+# or:
+rnex -v
+```

package/docs/examples/ai-workflows.md

@@ -0,0 +1,50 @@
+---
+title: Cross-Repo AI Workflows
+description: Practical walkthrough of executing cross-cutting features, workspace audits, and multi-agent refactoring with Repo Nexus.
+---
+
+# Cross-Repo AI Workflows
+
+One of the greatest challenges with AI coding assistants in multi-repo setups is context isolation: agents operating inside one repository cannot easily coordinate changes across upstream or downstream services.
+
+Repo Nexus equips AI assistants with standardized cross-repo workflows located in `.rnex/prompts/`.
+
+---
+
+## The Prompts Catalog
+
+When a workspace is initialized, Repo Nexus seeds `.rnex/prompts/` with specialized agent workflow templates:
+
+| Workflow Prompt | Target Agent Goal |
+|:---|:---|
+| `rnex-cross-repo-feature.md` | Implement an end-to-end feature across backend, frontend, and shared contracts. |
+| `rnex-workspace-audit.md` | Audit git status, unpushed branches, dirty files, and schema health. |
+| `rnex-wiki-ingest.md` | Ingest raw documentation from `/raw/` into Karpathy LLM Wiki pages. |
+| `rnex-wiki-lint.md` | Validate markdown links, compute backlinks, and update the master index. |
+
+---
+
+## Executing a Cross-Repo Feature
+
+### 1. Invoke the Prompt in Your AI Assistant
+In Claude Code, Cursor, or Gemini, invoke the workflow:
+
+```text
+Follow the workflow in .rnex/prompts/rnex-cross-repo-feature.md to add OAuth2 login support across backend and web-client.
+```
+
+### 2. Autonomous Execution Sequence
+The agent follows a 4-stage protocol:
+1. **Context Orientation**: Inspects `rnex.yaml` to identify member repositories and locate contract definitions in `repos/contracts/`.
+2. **Schema & Contract Definition**: Modifies the shared protocol or OpenAPI spec first.
+3. **Service Implementation**: Applies backend API handlers in `repos/backend/` and updates frontend client components in `repos/web-client/`.
+4. **Verification**: Executes workspace-wide verification via `rnex exec npm test`.
+
+### 3. Preserving Commits per Repository
+Because each repository in `./repos/` is a standard Git repository, the agent commits changes directly in each repository root without creating messy parent commit dependencies:
+
+```bash
+cd repos/contracts && git commit -m "feat(auth): define oauth2 schema"
+cd ../backend && git commit -m "feat(auth): implement oauth2 endpoints"
+cd ../web-client && git commit -m "feat(auth): add login buttons"
+```

package/docs/examples/local-overrides.md

@@ -0,0 +1,70 @@
+---
+title: Workstation Local Overrides
+description: How to customize your local developer environment with .local.rnex.yaml without polluting team-wide configuration.
+---
+
+# Workstation Local Overrides
+
+In large multi-repo workspaces, not every engineer needs all repositories cloned, nor do all developers use the same IDE. Repo Nexus solves this using `.local.rnex.yaml`.
+
+---
+
+## Scenario: Resource-Constrained Laptop
+
+Your team's `rnex.yaml` declares 6 services including a heavy analytics pipeline and machine learning models. You are working exclusively on the frontend and user auth API.
+
+### Creating `.local.rnex.yaml`
+
+Create `.local.rnex.yaml` in your workspace root (it is gitignored automatically):
+
+```yaml
+repos:
+  # Disable repositories you do not need
+  ml-service:
+    enabled: false
+  analytics-pipeline:
+    enabled: false
+  big-data-spark:
+    enabled: false
+
+  # Pin your personal active branch for backend
+  backend:
+    branch: feature/auth-refactor
+
+plugins:
+  # Enable your personal editor preference
+  cursor:
+    rules: true
+```
+
+### Apply the Overrides
+
+Run `rnex fix` to reconcile your local configuration:
+
+```bash
+rnex fix
+```
+
+```text
+[rnex] Reconciling configuration...
+[rnex] Loaded team configuration: rnex.yaml
+[rnex] Applied local overrides: .local.rnex.yaml
+[rnex] 3 repositories active, 3 disabled.
+[rnex] Updated workspace.code-workspace.
+```
+
+---
+
+## Toggling via CLI
+
+You can also set local overrides directly from the CLI using the `--local` flag:
+
+```bash
+# Disable a repository locally
+rnex disable --local analytics-pipeline
+
+# Enable a personal plugin locally
+rnex plugin enable --local gemini
+```
+
+Both commands update `.local.rnex.yaml`, leaving team-wide `rnex.yaml` completely untouched for Git commits.