docs: codex plugin README clarity and update instructions

.agents/plugins/marketplace.json

@@ -8,7 +8,7 @@
       "name": "ralph-specum",
       "source": {
         "source": "local",
-        "path": "./plugins/codex"
+        "path": "./plugins/ralph-specum-codex"
       },
       "policy": {
         "installation": "AVAILABLE"

.github/workflows/bats-tests.yml

@@ -4,15 +4,15 @@ on:
   push:
     paths:
       - 'plugins/**/*.sh'
-      - 'plugins/codex/**'
+      - 'plugins/ralph-specum-codex/**'
       - 'tests/**/*.bats'
       - 'tests/helpers/**'
       - 'tests/fixtures/**'
       - '.github/workflows/bats-tests.yml'
   pull_request:
     paths:
       - 'plugins/**/*.sh'
-      - 'plugins/codex/**'
+      - 'plugins/ralph-specum-codex/**'
       - 'tests/**/*.bats'
       - 'tests/helpers/**'
       - 'tests/fixtures/**'

.github/workflows/codex-version-check.yml

@@ -3,7 +3,7 @@ name: Codex Version Check
 on:
   pull_request:
     paths:
-      - 'plugins/codex/**'
+      - 'plugins/ralph-specum-codex/**'
 
 jobs:
   check-version-bump:
@@ -18,7 +18,7 @@ jobs:
       - name: Check Codex manifest version
         run: |
           BASE_BRANCH="${{ github.base_ref }}"
-          MANIFEST="plugins/codex/.codex-plugin/plugin.json"
+          MANIFEST="plugins/ralph-specum-codex/.codex-plugin/plugin.json"
 
           version_greater() {
             local v1=$1 v2=$2
@@ -50,8 +50,8 @@ jobs:
             exit 1
           fi
 
-          if ! git diff --quiet "origin/${BASE_BRANCH}...HEAD" -- plugins/codex/; then
-            echo "Detected changes under plugins/codex/"
+          if ! git diff --quiet "origin/${BASE_BRANCH}...HEAD" -- plugins/ralph-specum-codex/; then
+            echo "Detected changes under plugins/ralph-specum-codex/"
           else
             echo "No Codex package changes detected"
             exit 0

README.md

@@ -51,45 +51,76 @@ Named after the [Ralph agentic loop pattern](https://ghuntley.com/ralph/) and ev
 
 ### Codex
 
-**Personal install** (available in every project you open with Codex):
+> **Prerequisite:** Install the [Codex CLI](https://github.com/openai/codex) first: `npm install -g @openai/codex`
+
+<details>
+<summary>Personal install (available in every project)</summary>
+
+Run these commands from any directory. They clone the repo to a temp folder, copy the plugin to your Codex plugins directory, and clean up.
 
 ```bash
-# 1. Download the plugin
+# 1. Clone the Smart Ralph repo
 git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph
+
+# 2. Copy the Codex plugin into your personal plugins directory
 mkdir -p ~/.codex/plugins
-cp -R /tmp/smart-ralph/plugins/codex ~/.codex/plugins/codex
-rm -rf /tmp/smart-ralph
+cp -R /tmp/smart-ralph/plugins/ralph-specum-codex ~/.codex/plugins/ralph-specum-codex
 
-# 2. Register it in your personal marketplace
+# 3. Create a marketplace entry so Codex can discover the plugin
 mkdir -p ~/.agents/plugins
 cat > ~/.agents/plugins/marketplace.json << 'EOF'
 {
   "name": "smart-ralph",
   "plugins": [{
     "name": "ralph-specum",
-    "source": {"source": "local", "path": "~/.codex/plugins/codex"},
+    "source": {"source": "local", "path": "~/.codex/plugins/ralph-specum-codex"},
     "policy": {"installation": "AVAILABLE"},
     "category": "Productivity"
   }]
 }
 EOF
 
-# 3. Restart Codex, open the plugin directory, install ralph-specum
+# 4. Clean up
+rm -rf /tmp/smart-ralph
 ```
 
-**Per-project install** (available only in one repo):
+</details>
+
+<details>
+<summary>Per-project install (one repo only)</summary>
+
+Run these commands from your project root directory (the repo where you want to use Ralph).
 
 ```bash
-# From your project root
+# 1. Clone the Smart Ralph repo
 git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph
+
+# 2. Copy the Codex plugin into your project
 mkdir -p ./plugins
-cp -R /tmp/smart-ralph/plugins/codex ./plugins/codex
-cp -R /tmp/smart-ralph/.agents ./.agents
-rm -rf /tmp/smart-ralph
+cp -R /tmp/smart-ralph/plugins/ralph-specum-codex ./plugins/ralph-specum-codex
+
+# 3. Create a marketplace entry in your project
+mkdir -p ./.agents/plugins
+cat > ./.agents/plugins/marketplace.json << 'EOF'
+{
+  "name": "smart-ralph",
+  "plugins": [{
+    "name": "ralph-specum",
+    "source": {"source": "local", "path": "./plugins/ralph-specum-codex"},
+    "policy": {"installation": "AVAILABLE"},
+    "category": "Productivity"
+  }]
+}
+EOF
 
-# Restart Codex, open the plugin directory, install ralph-specum
+# 4. Clean up
+rm -rf /tmp/smart-ralph
 ```
 
+</details>
+
+After either method: restart Codex, open the plugin directory, and install `ralph-specum`.
+
 **Optional**: Enable the Stop hook for automatic task execution:
 
 ```toml
@@ -98,39 +129,27 @@ rm -rf /tmp/smart-ralph
 codex_hooks = true
 ```
 
-**Or just ask Codex to do it for you:**
+See [`plugins/ralph-specum-codex/README.md`](plugins/ralph-specum-codex/README.md) for full details.
 
-Install prompt:
-```text
-Install the Smart Ralph Codex plugin from repo tzachbon/smart-ralph.
-The plugin is at plugins/codex. Copy it to my personal
-plugins directory at ~/.codex/plugins/codex, create a
-personal marketplace entry at ~/.agents/plugins/marketplace.json,
-and restart Codex.
-```
+**Updating** (run from any directory):
 
-Migrate prompt (if upgrading from the old `platforms/codex/` skills):
-```text
-Migrate from the old Smart Ralph Codex skills to the new plugin.
-Remove all ralph-specum* skills from ~/.codex/skills/ and
-$CODEX_HOME/skills/. Then install the Smart Ralph plugin from
-repo tzachbon/smart-ralph at plugins/codex into
-my personal plugins directory. Create the marketplace entry
-and restart Codex.
+```bash
+rm -rf /tmp/smart-ralph
+git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph
+cp -R /tmp/smart-ralph/plugins/ralph-specum-codex ~/.codex/plugins/ralph-specum-codex
+rm -rf /tmp/smart-ralph
+# Restart Codex
 ```
 
-See [`plugins/codex/README.md`](plugins/codex/README.md) for agent configs and full details.
+For per-project installs, replace `~/.codex/plugins/ralph-specum-codex` with `./plugins/ralph-specum-codex` (run from your project root).
 
 <details>
 <summary>Migrating from old skills (platforms/codex/)?</summary>
 
-The old `platforms/codex/` skill-installer approach is deprecated. Remove your old skill installs and switch to the plugin:
-
-1. Remove old skills: `rm -rf $CODEX_HOME/skills/ralph-specum*`
-2. Follow the plugin install steps above
-3. All 15 skills ship in one package now
+1. Remove old skills: `rm -rf ~/.codex/skills/ralph-specum*`
+2. Follow the install steps above
 
-See the [migration guide](plugins/codex/README.md#migration-from-old-skills-platformscodex) for full details.
+See the [migration guide](plugins/ralph-specum-codex/README.md#migration-from-old-skills-platformscodex) for details.
 
 </details>
 
@@ -384,7 +403,7 @@ smart-ralph/
 │   │   ├── hooks/              # Stop watcher (controls execution loop)
 │   │   ├── templates/          # Spec templates
 │   │   └── schemas/            # Validation schemas
-│   ├── codex/                  # Codex plugin (full parity)
+│   ├── ralph-specum-codex/     # Codex plugin (full parity)
 │   │   ├── .codex-plugin/
 │   │   │   └── plugin.json
 │   │   ├── skills/             # 15 skills ($ralph-specum-*)

plugins/codex/.codex-plugin/plugin.json → plugins/ralph-specum-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-specum",
-  "version": "4.10.0",
+  "version": "4.10.1",
   "description": "Spec-driven development for OpenAI Codex. Research, requirements, design, tasks, autonomous implementation, and epic triage for multi-spec feature decomposition.",
   "author": {
     "name": "tzachbon"