oh-my-codex-pennix 0.18.13

package/plugins/oh-my-codex/skills/design/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: design
+description: Canonical repo-local DESIGN.md workflow for product, UI/UX, and frontend decision source of truth
+---
+
+# Design Skill
+
+Use `$design` when product, UI/UX, frontend, or design-system decisions need a durable source of truth in the repository. This skill discovers existing design context, interviews for missing product/design information, and creates or refreshes repo-local `DESIGN.md` so future UI/UX/frontend work is grounded instead of improvised.
+
+## Purpose
+
+Make repo-local `DESIGN.md` source of truth and canonical design contract for the current repository:
+
+`existing repo evidence -> missing-context interview -> create/refresh DESIGN.md -> use DESIGN.md for UI/UX/frontend decisions`.
+
+The output is not a pixel-matching loop and not a one-off visual critique. It is the maintained design brief/checklist that implementation, review, and future visual work should cite.
+
+## Use when
+
+- The user asks for design direction, UX guidance, frontend planning, or design-system alignment.
+- A repo needs a design brief before UI/frontend implementation begins.
+- Existing UI/components/assets/screenshots need to be summarized into a reusable design source of truth.
+- UI/UX/frontend decisions are ambiguous and should be resolved through product context, constraints, and documented principles.
+- A feature needs `DESIGN.md` created or refreshed before `$ralph`, a designer lane, or implementation work proceeds.
+
+## Do not use when
+
+- The user provides or requests a visual reference/image/live URL and wants measured implementation until screenshots match. Use `$visual-ralph` for that visual-reference implementation loop.
+- The task is pure backend/API/infrastructure work with no user-facing design consequence.
+- The user only asks to compare screenshots or score visual fidelity. Use `$visual-ralph` and its built-in visual verdict flow.
+
+## Relationship to `$visual-ralph`
+
+`$design` owns the durable repo design source of truth: product goals, users, IA, visual language, components, accessibility, constraints, and open questions in `DESIGN.md`.
+
+`$visual-ralph` owns implementation against an approved generated/static/live-URL visual reference, with screenshot capture, Visual Ralph verdict scoring, and pixel-diff evidence. `$visual-ralph` may read `DESIGN.md`, and it may leave design-system artifacts behind, but it does not replace the `DESIGN.md` discovery/interview/refresh workflow.
+
+If both are needed, run `$design` first to establish the design contract, then run `$visual-ralph` only after the visual reference/baseline is approved.
+
+## Workflow
+
+### 1. Discover local design evidence
+
+Inspect the repository before writing guidance. Look for:
+
+- `DESIGN.md`, `docs/design*`, `docs/ux*`, `docs/frontend*`, `README.md`, product specs, PRDs, and issue notes.
+- Existing UI source: routes, pages, layouts, components, stories, examples, demos, theme files, CSS variables, Tailwind/theme config, tokens, icons, and assets.
+- Screenshots, mockups, brand files, logos, Figma/export notes, Storybook snapshots, Playwright screenshots, visual-regression baselines, or `.omx/artifacts/visual-ralph/*` references.
+- Accessibility, responsive, i18n, content, and platform constraints already encoded in code or docs.
+
+Record evidence with file paths. Distinguish observed facts from design inferences.
+
+### 2. Interview only for missing context
+
+Ask concise questions only when repo evidence cannot answer design-critical context. Prefer one focused round that closes the biggest gaps, such as:
+
+- target users/personas and jobs to be done,
+- product/business goals and non-goals,
+- brand personality or forbidden aesthetics,
+- primary flows and information architecture,
+- accessibility level, device/browser support, and implementation constraints,
+- existing design assets or references the repo does not contain.
+
+If the user wants autonomous progress or cannot answer, create `DESIGN.md` with explicit assumptions and open questions instead of blocking.
+
+### 3. Create or refresh `DESIGN.md`
+
+Use the structure below. Preserve useful existing content, remove contradictions, and mark unknowns as open questions. Keep it actionable for implementers and reviewers.
+
+#### Required `DESIGN.md` structure/checklist
+
+```markdown
+# Design
+
+## Source of truth
+- Status: Draft | Active | Needs refresh
+- Last refreshed: YYYY-MM-DD
+- Primary product surfaces:
+- Evidence reviewed:
+
+## Brand
+- Personality:
+- Trust signals:
+- Avoid:
+
+## Product goals
+- Goals:
+- Non-goals:
+- Success signals:
+
+## Personas and jobs
+- Primary personas:
+- User jobs:
+- Key contexts of use:
+
+## Information architecture
+- Primary navigation:
+- Core routes/screens:
+- Content hierarchy:
+
+## Design principles
+- Principle 1:
+- Principle 2:
+- Tradeoffs:
+
+## Visual language
+- Color:
+- Typography:
+- Spacing/layout rhythm:
+- Shape/radius/elevation:
+- Motion:
+- Imagery/iconography:
+
+## Components
+- Existing components to reuse:
+- New/changed components:
+- Variants and states:
+- Token/component ownership:
+
+## Accessibility
+- Target standard:
+- Keyboard/focus behavior:
+- Contrast/readability:
+- Screen-reader semantics:
+- Reduced motion and sensory considerations:
+
+## Responsive behavior
+- Supported breakpoints/devices:
+- Layout adaptations:
+- Touch/hover differences:
+
+## Interaction states
+- Loading:
+- Empty:
+- Error:
+- Success:
+- Disabled:
+- Offline/slow network, if applicable:
+
+## Content voice
+- Tone:
+- Terminology:
+- Microcopy rules:
+
+## Implementation constraints
+- Framework/styling system:
+- Design-token constraints:
+- Performance constraints:
+- Compatibility constraints:
+- Test/screenshot expectations:
+
+## Open questions
+- [ ] Question / owner / impact
+```
+
+### 4. Use `DESIGN.md` as the decision contract
+
+For UI/UX/frontend work after the refresh:
+
+- Cite the relevant `DESIGN.md` sections before making design choices.
+- Prefer existing components, tokens, and documented constraints.
+- If implementation reveals a design contradiction, update `DESIGN.md` or add an open question before proceeding.
+- Do not introduce a new design-system layer when existing repo-native patterns can be extended.
+
+### 5. Handoff to implementation or Visual Ralph when appropriate
+
+- For normal frontend implementation, hand off with the relevant `DESIGN.md` sections, repo evidence, and acceptance criteria.
+- For visual-reference/image/live-URL matching, hand off to `$visual-ralph` with the approved reference/baseline and note that `DESIGN.md` is supporting context, not the visual verdict target.
+
+## Completion checklist
+
+Do not declare the design workflow complete until:
+
+- Existing design docs/assets/components/screenshots have been inspected or explicitly noted as absent.
+- Missing product/design context has been answered, assumed, or listed in `DESIGN.md` open questions.
+- `DESIGN.md` exists at the repo root and contains all required checklist sections.
+- UI/UX/frontend recommendations cite `DESIGN.md` rather than relying on unstated preferences.
+- Any `$visual-ralph` handoff is clearly separated as visual implementation matching, not DESIGN.md governance.
+
+Task: {{ARGUMENTS}}

package/plugins/oh-my-codex/skills/doctor/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: doctor
+description: Diagnose and fix oh-my-codex installation issues
+---
+
+# Doctor Skill
+
+Note: All `~/.codex/...` paths in this guide respect `CODEX_HOME` when that environment variable is set.
+
+## Canonical skill root
+
+OMX installs skills to `${CODEX_HOME:-~/.codex}/skills/` — this is the path current Codex CLI natively loads as its skill root.
+
+`~/.agents/skills/` is a **historical legacy path** from an older Codex CLI release, before Codex settled on `~/.codex` as its home directory. Current Codex CLI and OMX no longer write there.
+
+**In a mixed OMX + plain Codex environment:**
+- **Use**: `${CODEX_HOME:-~/.codex}/skills/` (user scope) or `.codex/skills/` (project scope)
+- **Clean up if present**: `~/.agents/skills/` — if this still exists alongside the canonical root, Codex's Enable/Disable Skills UI will show duplicate entries for any skill present in both trees
+- **Interop rule**: OMX writes only to the canonical path; archive or remove `~/.agents/skills/` once you have confirmed `${CODEX_HOME:-~/.codex}/skills/` is your active root
+
+## Task: Run Installation Diagnostics
+
+You are the OMX Doctor - diagnose and fix installation issues.
+
+### Step 1: Check Plugin Version
+
+Official Codex plugin caches are marketplace- and version-scoped, for example `${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/oh-my-codex/$VERSION/`. Local installs may use `local` as the version identifier.
+
+```bash
+# Get installed plugin cache versions across marketplaces.
+# Cache shape: $PLUGIN_CACHE_ROOT/$MARKETPLACE_NAME/oh-my-codex/$PLUGIN_VERSION/
+PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
+CACHE_ENTRIES=$(find "$PLUGIN_CACHE_ROOT" -path "*/oh-my-codex/*" -mindepth 3 -maxdepth 3 -type d 2>/dev/null)
+
+if [[ -z "$CACHE_ENTRIES" ]]; then
+  echo "Installed plugin cache: none"
+else
+  while IFS= read -r VERSION_DIR; do
+    MARKETPLACE_NAME=$(basename "$(dirname "$(dirname "$VERSION_DIR")")")
+    PLUGIN_VERSION=$(basename "$VERSION_DIR")
+    printf 'Installed plugin cache: marketplace=%s version=%s path=%s\n' "$MARKETPLACE_NAME" "$PLUGIN_VERSION" "$VERSION_DIR"
+  done <<< "$CACHE_ENTRIES"
+fi
+
+# Get latest from npm
+LATEST=$(npm view oh-my-codex version 2>/dev/null)
+echo "Latest npm: $LATEST"
+```
+
+**Diagnosis**:
+- If no cache entry exists: INFO - plugin marketplace artifact not cached; this may be normal when OMX was installed only through npm/setup
+- Compare each printed `PLUGIN_VERSION` with `LATEST`; if it differs and is not `local`: WARN - outdated plugin cache
+- If one marketplace has multiple version directories: WARN - stale cache for that marketplace/plugin pair
+- Remember: plugin install/discovery is not a replacement for `npm install -g oh-my-codex` plus `omx setup`; the packaged plugin carries plugin-scoped companion metadata for optional MCP compatibility servers and apps, with first-party MCP disabled by default, while native/runtime hooks and the rest of OMX runtime wiring stay setup-owned
+
+### Step 2: Check Hook Configuration (config.toml + legacy settings.json)
+
+Check `~/.codex/config.toml` first (current Codex config), then check legacy `~/.codex/settings.json` only if it exists.
+
+Look for hook entries pointing to removed scripts like:
+- `bash $HOME/.codex/hooks/keyword-detector.sh`
+- `bash $HOME/.codex/hooks/persistent-mode.sh`
+- `bash $HOME/.codex/hooks/session-start.sh`
+
+**Diagnosis**:
+- If found: CRITICAL - legacy hooks causing duplicates
+
+### Step 3: Check for Legacy Bash Hook Scripts
+
+```bash
+ls -la ~/.codex/hooks/*.sh 2>/dev/null
+```
+
+**Diagnosis**:
+- If `keyword-detector.sh`, `persistent-mode.sh`, `session-start.sh`, or `stop-continuation.sh` exist: WARN - legacy scripts (can cause confusion)
+
+### Step 4: Check AGENTS.md
+
+```bash
+# Check if AGENTS.md exists
+ls -la ~/.codex/AGENTS.md 2>/dev/null
+
+# Check for OMX marker
+grep -q "oh-my-codex Multi-Agent System" ~/.codex/AGENTS.md 2>/dev/null && echo "Has OMX config" || echo "Missing OMX config"
+```
+
+**Diagnosis**:
+- If missing: CRITICAL - AGENTS.md not configured
+- If missing OMX marker: WARN - outdated AGENTS.md
+
+### Step 5: Check for Stale Plugin Cache
+
+```bash
+# List marketplace/version cache entries for this plugin
+PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
+find "$PLUGIN_CACHE_ROOT" -path "*/oh-my-codex/*" -mindepth 3 -maxdepth 3 -type d 2>/dev/null \
+  | while IFS= read -r VERSION_DIR; do
+      MARKETPLACE_NAME=$(basename "$(dirname "$(dirname "$VERSION_DIR")")")
+      PLUGIN_VERSION=$(basename "$VERSION_DIR")
+      printf '%s\t%s\n' "$MARKETPLACE_NAME" "$PLUGIN_VERSION"
+    done
+```
+
+**Diagnosis**:
+- If a single marketplace lists multiple versions: WARN - multiple cached versions for that marketplace/plugin pair (cleanup recommended)
+
+### Step 6: Check for Legacy Curl-Installed Content
+
+Check for legacy agents, commands, and historical legacy skill roots from older installs/migrations:
+
+```bash
+# Check for legacy agents directory
+ls -la ~/.codex/agents/ 2>/dev/null
+
+# Check for legacy commands directory
+ls -la ~/.codex/commands/ 2>/dev/null
+
+# Check canonical current skills directory
+ls -la ${CODEX_HOME:-~/.codex}/skills/ 2>/dev/null
+
+# Check historical legacy skill directory
+ls -la ~/.agents/skills/ 2>/dev/null
+```
+
+**Diagnosis**:
+- If `~/.codex/agents/` exists with oh-my-codex-related files: WARN - legacy generated agents or hand-installed role files. The Codex plugin can package reusable workflows plus plugin-scoped companion metadata for optional MCP/apps; legacy setup installs native agents, while plugin setup archives stale legacy native-agent files and keeps config/hooks current.
+- If `~/.codex/commands/` exists with oh-my-codex-related files: WARN - legacy command files from older installs. Current OMX uses skills/workflows plus setup-managed native surfaces.
+- If `${CODEX_HOME:-~/.codex}/skills/` exists with OMX skills: OK - canonical current user skill root
+- If `~/.agents/skills/` exists: WARN - historical legacy skill root that can overlap with `${CODEX_HOME:-~/.codex}/skills/` and cause duplicate Enable/Disable Skills entries
+
+Look for files like:
+- `architect.md`, `researcher.md`, `explore.md`, `executor.md`, etc. in agents/
+- `ultrawork.md`, `deepsearch.md`, etc. in commands/
+- Any oh-my-codex-related `.md` files in skills/
+
+---
+
+## Report Format
+
+After running all checks, output a report:
+
+```
+## OMX Doctor Report
+
+### Summary
+[HEALTHY / ISSUES FOUND]
+
+### Checks
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Plugin Version | OK/WARN/CRITICAL | ... |
+| Hook Config (config.toml / legacy settings.json) | OK/CRITICAL | ... |
+| Legacy Scripts (~/.codex/hooks/) | OK/WARN | ... |
+| AGENTS.md | OK/WARN/CRITICAL | ... |
+| Plugin Cache | OK/WARN | ... |
+| Legacy Agents (~/.codex/agents/) | OK/WARN | ... |
+| Legacy Commands (~/.codex/commands/) | OK/WARN | ... |
+| Skills (${CODEX_HOME:-~/.codex}/skills) | OK/WARN | ... |
+| Legacy Skill Root (~/.agents/skills) | OK/WARN | ... |
+
+### Issues Found
+1. [Issue description]
+2. [Issue description]
+
+### Recommended Fixes
+[List fixes based on issues]
+```
+
+---
+
+## Auto-Fix (if user confirms)
+
+If issues found, ask user: "Would you like me to fix these issues automatically?"
+
+If yes, apply fixes:
+
+### Fix: Legacy Hooks in legacy settings.json
+If `~/.codex/settings.json` exists, remove the legacy `"hooks"` section (keep other settings intact).
+
+### Fix: Legacy Bash Scripts
+```bash
+rm -f ~/.codex/hooks/keyword-detector.sh
+rm -f ~/.codex/hooks/persistent-mode.sh
+rm -f ~/.codex/hooks/session-start.sh
+rm -f ~/.codex/hooks/stop-continuation.sh
+```
+
+### Fix: Outdated Plugin
+```bash
+# Global cache reset across all marketplaces for this plugin.
+# If you only want one marketplace, set MARKETPLACE_NAME and remove just that subtree instead.
+PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
+find "$PLUGIN_CACHE_ROOT" -path "*/oh-my-codex" -type d -prune -exec rm -rf {} +
+echo "Plugin cache cleared across all marketplaces. Restart Codex CLI to fetch the latest marketplace entry."
+```
+
+### Fix: Stale Cache (multiple versions)
+```bash
+# Keep only the newest version inside the selected marketplace/plugin cache.
+# Set MARKETPLACE_NAME to the exact marketplace printed in Step 1.
+PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
+PLUGIN_CACHE_DIR="$PLUGIN_CACHE_ROOT/$MARKETPLACE_NAME/oh-my-codex"
+KEEP_VERSION=$(for dir in "$PLUGIN_CACHE_DIR"/*; do [[ -d "$dir" ]] && basename "$dir"; done | sort -V | tail -1)
+if [[ -n "$KEEP_VERSION" ]]; then
+  find "$PLUGIN_CACHE_DIR" -mindepth 1 -maxdepth 1 -type d ! -name "$KEEP_VERSION" -exec rm -rf {} +
+fi
+```
+
+### Fix: Missing/Outdated AGENTS.md
+Fetch latest from GitHub and write to `~/.codex/AGENTS.md`:
+```
+WebFetch(url: "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-codex/main/docs/AGENTS.md", prompt: "Return the complete raw markdown content exactly as-is")
+```
+
+### Fix: Legacy Curl-Installed Content
+
+Remove legacy agents/commands plus the historical `~/.agents/skills` tree if it overlaps with the canonical `${CODEX_HOME:-~/.codex}/skills` install:
+
+```bash
+# Backup first (optional - ask user)
+# mv ~/.codex/agents ~/.codex/agents.bak
+# mv ~/.codex/commands ~/.codex/commands.bak
+# mv ~/.agents/skills ~/.agents/skills.bak
+
+# Or remove directly
+rm -rf ~/.codex/agents
+rm -rf ~/.codex/commands
+rm -rf ~/.agents/skills
+```
+
+**Note**: Only remove if these contain oh-my-codex-related files. If user has custom agents/commands/skills, warn them and ask before removing.
+
+---
+
+## Post-Fix
+
+After applying fixes, inform user:
+> Fixes applied. **Restart Codex CLI** for changes to take effect.

package/plugins/oh-my-codex/skills/hud/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: "hud"
+description: "Show or configure the OMX HUD (two-layer statusline)"
+role: "display"
+scope: ".omx/**"
+---
+
+# HUD Skill
+
+The OMX HUD uses a two-layer architecture:
+
+1. **Layer 1 - Codex built-in statusLine**: Real-time TUI footer showing model, git branch, and context usage. Configured via `[tui] status_line` in `~/.codex/config.toml`. Zero code required.
+
+2. **Layer 2 - `omx hud` CLI command**: Shows OMX-specific orchestration state (ralph, ultrawork, autopilot, team, pipeline, ecomode, turns). Reads `.omx/state/` files.
+
+## Quick Commands
+
+| Command | Description |
+|---------|-------------|
+| `omx hud` | Show current HUD (modes, turns, activity) |
+| `omx hud --watch` | Live-updating display (polls every 1s) |
+| `omx hud --json` | Raw state output for scripting |
+| `omx hud --preset=minimal` | Minimal display |
+| `omx hud --preset=focused` | Default display |
+| `omx hud --preset=full` | All elements |
+
+## Presets
+
+### minimal
+```
+[OMX] ralph:3/10 | turns:42
+```
+
+### focused (default)
+```
+[OMX] ralph:3/10 | ultrawork | team:3 workers | turns:42 | last:5s ago
+```
+
+### full
+```
+[OMX] ralph:3/10 | ultrawork | autopilot:execution | team:3 workers | pipeline:exec | turns:42 | last:5s ago | total-turns:156
+```
+
+## Setup
+
+`omx setup` automatically configures both layers:
+- Adds `[tui] status_line` to `~/.codex/config.toml` (Layer 1)
+- Writes `.omx/hud-config.json` with default preset (Layer 2)
+- Default preset is `focused`; if HUD/statusline changes do not appear, restart Codex CLI once.
+
+## Layer 1: Codex Built-in StatusLine
+
+Configured in `~/.codex/config.toml`:
+```toml
+[tui]
+status_line = ["model-with-reasoning", "git-branch", "context-remaining"]
+```
+
+Available built-in items (Codex CLI v0.101.0+):
+`model-name`, `model-with-reasoning`, `current-dir`, `project-root`, `git-branch`, `context-remaining`, `context-used`, `five-hour-limit`, `weekly-limit`, `codex-version`, `context-window-size`, `used-tokens`, `total-input-tokens`, `total-output-tokens`, `session-id`
+
+## Layer 2: OMX Orchestration HUD
+
+The `omx hud` command reads these state files:
+- `.omx/state/ralph-state.json` - Ralph loop iteration
+- `.omx/state/ultrawork-state.json` - Ultrawork mode
+- `.omx/state/autopilot-state.json` - Autopilot phase
+- `.omx/state/team-state.json` - Team workers
+- `.omx/state/pipeline-state.json` - Pipeline stage
+- `.omx/state/ecomode-state.json` - Ecomode active
+- `.omx/state/hud-state.json` - Last activity (from notify hook)
+- `.omx/metrics.json` - Turn counts
+
+## Configuration
+
+HUD config stored at `.omx/hud-config.json`:
+```json
+{
+  "preset": "focused"
+}
+```
+
+## Color Coding
+
+- **Green**: Normal/healthy
+- **Yellow**: Warning (ralph >70% of max)
+- **Red**: Critical (ralph >90% of max)
+
+## Troubleshooting
+
+If the TUI statusline is not showing:
+1. Ensure Codex CLI v0.101.0+ is installed
+2. Run `omx setup` to configure `[tui]` section
+3. Restart Codex CLI
+
+If `omx hud` shows "No active modes":
+- This is expected when no workflows are running
+- Start a workflow (ralph, autopilot, etc.) and check again

package/plugins/oh-my-codex/skills/omx-setup/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: omx-setup
+description: Setup and configure oh-my-codex using current CLI behavior
+---
+
+# OMX Setup
+
+Use this skill when users want to install or refresh oh-my-codex for the **current project plus user-level OMX directories**.
+
+## Command
+
+```bash
+omx setup [--force] [--merge-agents] [--dry-run] [--verbose] [--scope <user|project>] [--plugin|--legacy|--install-mode <legacy|plugin>]
+```
+
+If you only want lightweight `AGENTS.md` scaffolding for an existing repo or subtree, use `omx agents-init [path]` instead of full setup.
+
+Supported setup flags (current implementation):
+- `--force`: overwrite/reinstall managed artifacts where applicable
+- `--merge-agents`: when `AGENTS.md` already exists, preserve user-authored content and insert/refresh OMX-managed generated sections between explicit `<!-- OMX:AGENTS:START -->` / `<!-- OMX:AGENTS:END -->` markers
+- `--dry-run`: print actions without mutating files
+- `--verbose`: print per-file/per-step details
+- `--scope`: choose install scope (`user`, `project`)
+- `--plugin`: use Codex plugin delivery for bundled skills while archiving/removing legacy OMX-managed prompts/skills, refreshing setup-owned native agent TOMLs for `agent_type` routing, and keeping setup-owned runtime hooks
+- `--legacy`: use legacy setup delivery, overriding any persisted plugin install mode
+- `--install-mode`: explicitly choose setup delivery mode (`legacy` or `plugin`); canonical form for scripted setup
+
+## What this setup actually does
+
+`omx setup` performs these steps:
+
+1. Resolve setup scope:
+   - `--scope` explicit value
+   - else persisted `./.omx/setup-scope.json` (with automatic migration of legacy values)
+   - if a TTY user has persisted setup preferences, `omx setup` first summarizes the recorded choices and asks whether to **keep**, **review/change**, or **reset** them
+   - else interactive prompt on TTY (default `user`)
+   - else default `user` (safe for CI/tests)
+2. If scope is `user`, resolve user skill delivery mode:
+   - explicit `--plugin`, `--legacy`, or `--install-mode legacy|plugin`, if present
+   - persisted install mode in `./.omx/setup-scope.json`, if present and the TTY review decision is `keep`
+   - else discovered installed plugin cache under `${CODEX_HOME:-~/.codex}/plugins/cache/**/.codex-plugin/plugin.json` with `name: oh-my-codex` makes `plugin` the default
+   - else interactive prompt on TTY (`legacy` by default, or `plugin` when a plugin cache is discovered)
+   - else default `legacy` unless a plugin cache is discovered
+3. Create directories and persist effective scope/install mode
+4. In legacy mode, install prompts/native agents/skills and merge full config.toml. In plugin mode, archive/remove legacy OMX-managed prompts/skills, refresh installable native agent TOMLs for `agent_type` routing, clean up stale generated non-installable native agents, and keep native Codex hooks installed.
+5. Verify Team CLI API interop markers exist in built `dist/cli/team.js`
+6. Generate AGENTS.md defaults only when selected/allowed (or legacy behavior outside plugin mode)
+7. Configure notify hook references outside plugin mode and write `./.omx/hud-config.json`
+
+## Important behavior notes
+
+- `omx setup` prompts for scope when no scope is provided and stdin/stdout are TTY. If `./.omx/setup-scope.json` already exists, setup now summarizes the saved choices first and asks whether to keep them, review/change them, or reset and behave like a fresh setup run.
+- Non-interactive setup never blocks for this review prompt: it keeps deterministic CLI/persisted/default behavior for CI and scripted installs.
+- In `user` scope, `omx setup` also prompts for skill delivery mode when no prior install mode is kept; installed plugin cache discovery makes plugin mode the default prompt/non-interactive choice.
+- Local project orchestration file is `./AGENTS.md` (project root).
+- If `AGENTS.md` exists and neither `--force` nor `--merge-agents` is used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.
+- Use `--merge-agents` to keep existing project guidance while allowing setup to refresh OMX-managed AGENTS sections and the generated model capability table idempotently.
+- Scope targets:
+  - `user`: user directories (`~/.codex`, `~/.codex/skills`, `~/.omx/agents`)
+  - `project`: local directories (`./.codex`, `./.codex/skills`, `./.omx/agents`)
+- User-scope skill delivery targets:
+  - `legacy`: keep installing/updating OMX skills in the resolved user skill root
+  - `plugin`: rely on Codex plugin discovery for bundled skills and plugin-scoped lifecycle hooks when Codex reports `plugin_hooks`; archive/remove legacy OMX-managed prompts/skills, refresh installable setup-owned native agent TOMLs for `agent_type` routing, and remove only stale generated/non-installable native agents. Setup still enables setup-owned runtime feature flags (`plugin_hooks = true` and `goals = true` when supported, or legacy setup-managed `hooks`/`codex_hooks` fallback when plugin hooks are not reported).
+- Migration hint: in `user` scope, if historical `~/.agents/skills` still exists alongside `${CODEX_HOME:-~/.codex}/skills`, current setup prints a cleanup hint. **Why the paths differ**: `${CODEX_HOME:-~/.codex}/skills/` is the path current Codex CLI natively loads as its skill root; `~/.agents/skills/` was the skill root in an older Codex CLI release before `~/.codex` became the standard home directory. OMX writes only to the canonical `${CODEX_HOME:-~/.codex}/skills/` path. When both directories exist simultaneously, Codex discovers skills from both trees and may show duplicate entries in Enable/Disable Skills. Archive or remove `~/.agents/skills/` to resolve this.
+- If persisted scope is `project`, `omx` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
+- Plugin mode prompts separately for optional AGENTS.md defaults and optional `developer_instructions` defaults. If `developer_instructions` already exists, setup asks before overwriting it; non-interactive runs preserve it.
+- With `--force` or `--merge-agents`, AGENTS updates may still be skipped if an active OMX session is detected (safety guard).
+- Legacy persisted scope values (`project-local`) are automatically migrated to `project` with a one-time warning.
+
+## Setup-owned configuration surfaces
+
+Use this map when reconciling setup behavior or debugging a confusing install:
+
+| Surface | Owner | Notes |
+| --- | --- | --- |
+| `./.omx/setup-scope.json` | `omx setup` | Persists setup scope and user-scope skill delivery mode. TTY reruns summarize it and offer keep/review/reset. |
+| `~/.codex/config.toml` / `./.codex/config.toml` | `omx setup` generated blocks + user edits | Setup refreshes OMX-managed blocks while preserving supported manual content; setup-owned runtime feature flags include `multi_agent`, `child_agents_md`, the Codex hook feature flag (`hooks` or legacy `codex_hooks`), and `goals`. |
+| `~/.codex/hooks.json` / `./.codex/hooks.json` | `omx setup` shared ownership | Setup owns OMX native hook wrappers and preserves user-owned hooks. |
+| prompts, skills, native agents | `omx setup` or Codex plugin delivery | Legacy mode installs local files; plugin mode relies on plugin discovery for bundled skills, archives/removes legacy OMX-managed prompt/skill copies, and refreshes setup-owned native agent TOMLs for `agent_type` routing while cleaning up stale generated/non-installable native agents. |
+| `AGENTS.md` | `omx setup` with overwrite safety | Generated defaults or managed refreshes are guarded by force/session checks. |
+| `./.omx/hud-config.json` | `omx setup` / `$hud` | Setup creates the focused default; `$hud` can adjust it later. |
+| notification hooks | `omx setup` / `$configure-notifications` | Setup wires defaults outside plugin skill delivery; notification skill owns deeper provider configuration. |
+
+## If `$omx-setup` is missing or stale
+
+The source repo ships `skills/omx-setup/SKILL.md` and the catalog marks it active. If Codex does not show `$omx-setup`, treat it as an installation/discovery issue rather than a missing source skill:
+
+1. Run `omx setup --verbose` in the intended scope.
+2. Run `omx doctor` and check the reported setup scope, Codex home, skill root, and hook/config status.
+3. If using project scope, confirm `./.codex/skills/omx-setup/SKILL.md` exists.
+4. If using user scope, confirm `${CODEX_HOME:-~/.codex}/skills/omx-setup/SKILL.md` exists in legacy mode, or that the oh-my-codex plugin is installed/discovered in plugin mode.
+5. If duplicate/stale skills appear, check for legacy `~/.agents/skills` overlap and follow the cleanup hint printed by setup/doctor.
+
+## Recommended workflow
+
+1. Run setup:
+
+```bash
+omx setup --force --verbose
+```
+
+2. Verify installation:
+
+```bash
+omx doctor
+```
+
+3. Start Codex with OMX in the target project directory.
+
+## Expected verification indicators
+
+From `omx doctor`, expect:
+- Prompts installed (scope-dependent: user or project)
+- Skills installed (scope-dependent: user or project)
+- AGENTS.md found in project root
+- `.omx/state` exists
+- CLI-first config present in the scope target `config.toml`; first-party OMX MCP servers and shared MCP registry sync are omitted by default unless setup was run with `--mcp compat`
+
+## Troubleshooting
+
+- If using local source changes, run build first:
+
+```bash
+npm run build
+```
+
+- If your global `omx` points to another install, run local entrypoint:
+
+```bash
+node bin/omx.js setup --force --verbose
+node bin/omx.js doctor
+```
+
+- If AGENTS.md was not overwritten during `--force`, stop active OMX session and rerun setup.
+- If AGENTS.md was not merged during `--merge-agents`, stop active OMX session and rerun setup.