oh-my-codex 0.7.5 → 0.8.0

package/README.fr.md

@@ -0,0 +1,314 @@
+# oh-my-codex (OMX)
+
+<p align="center">
+  <img src="https://yeachan-heo.github.io/oh-my-codex-website/omx-character-nobg.png" alt="oh-my-codex character" width="280">
+  <br>
+  <em>Votre codex n'est pas seul.</em>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/oh-my-codex)](https://www.npmjs.com/package/oh-my-codex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+
+> **[Website](https://yeachan-heo.github.io/oh-my-codex-website/)** | **[Documentation](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** | **[CLI Reference](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** | **[Workflows](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** | **[GitHub](https://github.com/Yeachan-Heo/oh-my-codex)** | **[npm](https://www.npmjs.com/package/oh-my-codex)**
+
+Couche d'orchestration multi-agents pour [OpenAI Codex CLI](https://github.com/openai/codex).
+
+## Langues
+
+- [English](./README.md)
+- [한국어 (Korean)](./README.ko.md)
+- [日本語 (Japanese)](./README.ja.md)
+- [简体中文 (Chinese)](./README.zh.md)
+- [Tiếng Việt (Vietnamese)](./README.vi.md)
+- [Español (Spanish)](./README.es.md)
+- [Português (Portuguese)](./README.pt.md)
+- [Русский (Russian)](./README.ru.md)
+- [Türkçe (Turkish)](./README.tr.md)
+- [Deutsch (German)](./README.de.md)
+- [Français (French)](./README.fr.md)
+- [Italiano (Italian)](./README.it.md)
+
+
+OMX transforme Codex d'un agent mono-session en un système coordonné avec :
+- Des role prompts (`/prompts:name`) pour les agents spécialisés
+- Des workflow skills (`$name`) pour les modes d'exécution reproductibles
+- L'orchestration d'équipe dans tmux (`omx team`, `$team`)
+- Un état et une mémoire persistants via les serveurs MCP
+
+## Pourquoi OMX
+
+Codex CLI est performant pour les tâches directes. OMX ajoute de la structure pour les travaux plus importants :
+- Décomposition et exécution par étapes (`team-plan -> team-prd -> team-exec -> team-verify -> team-fix`)
+- État persistant du cycle de vie des modes (`.omx/state/`)
+- Surfaces de mémoire et notepad pour les sessions longue durée
+- Contrôles opérationnels pour le lancement, la vérification et l'annulation
+
+OMX est un add-on, pas un fork. Il utilise les points d'extension natifs de Codex.
+
+## Prérequis
+
+- macOS ou Linux (Windows via WSL2)
+- Node.js >= 20
+- Codex CLI installé (`npm install -g @openai/codex`)
+- Authentification Codex configurée
+
+## Démarrage rapide (3 minutes)
+
+```bash
+npm install -g oh-my-codex
+omx setup
+omx doctor
+```
+
+Profil de lancement recommandé pour les environnements de confiance :
+
+```bash
+omx --xhigh --madmax
+```
+
+## Nouveautés de la v0.5.0
+
+- **Configuration sensible au scope** avec `omx setup --scope user|project` pour des modes d'installation flexibles.
+- **Routage Spark worker** via `--spark` / `--madmax-spark` pour que les workers d'équipe puissent utiliser `gpt-5.3-codex-spark` sans forcer le modèle leader.
+- **Consolidation du catalogue** — suppression des prompts obsolètes (`deep-executor`, `scientist`) et de 9 skills obsolètes.
+- **Niveaux de verbosité des notifications** pour un contrôle fin de la sortie CCNotifier.
+
+## Première session
+
+Dans Codex :
+
+```text
+/prompts:architect "analyze current auth boundaries"
+/prompts:executor "implement input validation in login"
+$plan "ship OAuth callback safely"
+$team 3:executor "fix all TypeScript errors"
+```
+
+Depuis le terminal :
+
+```bash
+omx team 4:executor "parallelize a multi-module refactor"
+omx team status <team-name>
+omx team shutdown <team-name>
+```
+
+## Modèle de base
+
+OMX installe et connecte ces couches :
+
+```text
+User
+  -> Codex CLI
+    -> AGENTS.md (cerveau d'orchestration)
+    -> ~/.codex/prompts/*.md (catalogue de prompts d'agents)
+    -> ~/.agents/skills/*/SKILL.md (catalogue de skills)
+    -> ~/.codex/config.toml (fonctionnalités, notifications, MCP)
+    -> .omx/ (état d'exécution, mémoire, plans, journaux)
+```
+
+## Commandes principales
+
+```bash
+omx                # Lancer Codex (+ HUD dans tmux si disponible)
+omx setup          # Installer prompts/skills/config par scope + projet AGENTS.md/.omx
+omx doctor         # Diagnostics d'installation/exécution
+omx doctor --team  # Diagnostics Team/Swarm
+omx team ...       # Démarrer/statut/reprendre/arrêter les workers d'équipe tmux
+omx status         # Afficher les modes actifs
+omx cancel         # Annuler les modes d'exécution actifs
+omx reasoning <mode> # low|medium|high|xhigh
+omx tmux-hook ...  # init|status|validate|test
+omx hooks ...      # init|status|validate|test (workflow d'extension de plugins)
+omx hud ...        # --watch|--json|--preset
+omx help
+```
+
+## Extension Hooks (Surface additive)
+
+OMX inclut désormais `omx hooks` pour l'échafaudage et la validation de plugins.
+
+- `omx tmux-hook` reste supporté et inchangé.
+- `omx hooks` est additif et ne remplace pas les workflows tmux-hook.
+- Les fichiers de plugins se trouvent dans `.omx/hooks/*.mjs`.
+- Les plugins sont désactivés par défaut ; activez-les avec `OMX_HOOK_PLUGINS=1`.
+
+Consultez `docs/hooks-extension.md` pour le workflow d'extension complet et le modèle d'événements.
+
+## Flags de lancement
+
+```bash
+--yolo
+--high
+--xhigh
+--madmax
+--force
+--dry-run
+--verbose
+--scope <user|project>  # uniquement pour setup
+```
+
+`--madmax` correspond à Codex `--dangerously-bypass-approvals-and-sandbox`.
+À utiliser uniquement dans des environnements sandbox de confiance/externes.
+
+### Politique MCP workingDirectory (durcissement optionnel)
+
+Par défaut, les outils MCP état/mémoire/trace acceptent le `workingDirectory` fourni par l'appelant.
+Pour restreindre cela, définissez une liste d'autorisation de racines :
+
+```bash
+export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"
+```
+
+Lorsque défini, les valeurs `workingDirectory` en dehors de ces racines sont rejetées.
+
+## Contrôle Codex-First des prompts
+
+Par défaut, OMX injecte :
+
+```text
+-c model_instructions_file="<cwd>/AGENTS.md"
+```
+
+Cela superpose les instructions `AGENTS.md` du projet dans les instructions de lancement de Codex.
+Cela étend le comportement de Codex, mais ne remplace/contourne pas les politiques système de base de Codex.
+
+Contrôles :
+
+```bash
+OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx     # désactiver l'injection AGENTS.md
+OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx
+```
+
+## Mode équipe
+
+Utilisez le mode équipe pour les travaux importants qui bénéficient de workers parallèles.
+
+Cycle de vie :
+
+```text
+start -> assign scoped lanes -> monitor -> verify terminal tasks -> shutdown
+```
+
+Commandes opérationnelles :
+
+```bash
+omx team <args>
+omx team status <team-name>
+omx team resume <team-name>
+omx team shutdown <team-name>
+```
+
+Règle importante : n'arrêtez pas tant que des tâches sont encore `in_progress`, sauf en cas d'abandon.
+
+### Politique de nettoyage Ralph
+
+Lorsqu'une équipe s'exécute en mode ralph (`omx team ralph ...`), le nettoyage à l'arrêt
+applique une politique dédiée qui diffère du chemin normal :
+
+| Comportement | Équipe normale | Équipe Ralph |
+|---|---|---|
+| Arrêt forcé en cas d'échec | Lance `shutdown_gate_blocked` | Contourne la porte, journalise l'événement `ralph_cleanup_policy` |
+| Suppression automatique des branches | Supprime les branches worktree lors du rollback | Préserve les branches (`skipBranchDeletion`) |
+| Journalisation de complétion | Événement standard `shutdown_gate` | Événement supplémentaire `ralph_cleanup_summary` avec détail des tâches |
+
+La politique ralph est auto-détectée depuis l'état du mode équipe (`linked_ralph`) ou
+peut être passée explicitement via `omx team shutdown <name> --ralph`.
+
+Sélection du CLI worker pour les workers d'équipe :
+
+```bash
+OMX_TEAM_WORKER_CLI=auto    # par défaut ; utilise claude quand worker --model contient "claude"
+OMX_TEAM_WORKER_CLI=codex   # forcer les workers Codex CLI
+OMX_TEAM_WORKER_CLI=claude  # forcer les workers Claude CLI
+OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude  # mix CLI par worker (longueur=1 ou nombre de workers)
+OMX_TEAM_AUTO_INTERRUPT_RETRY=0  # optionnel : désactiver le fallback adaptatif queue->resend
+```
+
+Notes :
+- Les arguments de lancement des workers sont toujours partagés via `OMX_TEAM_WORKER_LAUNCH_ARGS`.
+- `OMX_TEAM_WORKER_CLI_MAP` remplace `OMX_TEAM_WORKER_CLI` pour la sélection par worker.
+- La soumission de déclencheurs utilise par défaut des tentatives adaptatives (queue/submit, puis fallback sécurisé clear-line+resend si nécessaire).
+- En mode worker Claude, OMX lance les workers en tant que simple `claude` (pas d'arguments de lancement supplémentaires) et ignore les surcharges explicites `--model` / `--config` / `--effort` pour que Claude utilise le `settings.json` par défaut.
+
+## Ce que `omx setup` écrit
+
+- `.omx/setup-scope.json` (scope de setup persisté)
+- Installations dépendantes du scope :
+  - `user` : `~/.codex/prompts/`, `~/.agents/skills/`, `~/.codex/config.toml`, `~/.omx/agents/`
+  - `project` : `./.codex/prompts/`, `./.agents/skills/`, `./.codex/config.toml`, `./.omx/agents/`
+- Comportement au lancement : si le scope persisté est `project`, le lancement `omx` utilise automatiquement `CODEX_HOME=./.codex` (sauf si `CODEX_HOME` est déjà défini).
+- Le `AGENTS.md` existant est préservé par défaut. Lors des exécutions TTY interactives, setup demande confirmation avant d'écraser ; `--force` écrase sans demander (les vérifications de sécurité de session active s'appliquent toujours).
+- Mises à jour de `config.toml` (pour les deux scopes) :
+  - `notify = ["node", "..."]`
+  - `model_reasoning_effort = "high"`
+  - `developer_instructions = "..."`
+  - `[features] multi_agent = true, child_agents_md = true`
+  - Entrées de serveurs MCP (`omx_state`, `omx_memory`, `omx_code_intel`, `omx_trace`)
+  - `[tui] status_line`
+- `AGENTS.md` du projet
+- Répertoires d'exécution `.omx/` et configuration HUD
+
+## Agents et Skills
+
+- Prompts : `prompts/*.md` (installés dans `~/.codex/prompts/` pour `user`, `./.codex/prompts/` pour `project`)
+- Skills : `skills/*/SKILL.md` (installés dans `~/.agents/skills/` pour `user`, `./.agents/skills/` pour `project`)
+
+Exemples :
+- Agents : `architect`, `planner`, `executor`, `debugger`, `verifier`, `security-reviewer`
+- Skills : `autopilot`, `plan`, `team`, `ralph`, `ultrawork`, `cancel`
+
+## Structure du projet
+
+```text
+oh-my-codex/
+  bin/omx.js
+  src/
+    cli/
+    team/
+    mcp/
+    hooks/
+    hud/
+    config/
+    modes/
+    notifications/
+    verification/
+  prompts/
+  skills/
+  templates/
+  scripts/
+```
+
+## Développement
+
+```bash
+git clone https://github.com/Yeachan-Heo/oh-my-codex.git
+cd oh-my-codex
+npm install
+npm run build
+npm test
+```
+
+## Documentation
+
+- **[Documentation complète](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** — Guide complet
+- **[Référence CLI](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** — Toutes les commandes `omx`, flags et outils
+- **[Guide des notifications](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#notifications)** — Configuration Discord, Telegram, Slack et webhooks
+- **[Workflows recommandés](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** — Chaînes de skills éprouvées pour les tâches courantes
+- **[Notes de version](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#release-notes)** — Nouveautés de chaque version
+
+## Notes
+
+- Journal des modifications complet : `CHANGELOG.md`
+- Guide de migration (post-v0.4.4 mainline) : `docs/migration-mainline-post-v0.4.4.md`
+- Notes de couverture et parité : `COVERAGE.md`
+- Workflow d'extension hooks : `docs/hooks-extension.md`
+- Détails de configuration et contribution : `CONTRIBUTING.md`
+
+## Remerciements
+
+Inspiré par [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), adapté pour Codex CLI.
+
+## Licence
+
+MIT

package/README.it.md

@@ -0,0 +1,314 @@
+# oh-my-codex (OMX)
+
+<p align="center">
+  <img src="https://yeachan-heo.github.io/oh-my-codex-website/omx-character-nobg.png" alt="oh-my-codex character" width="280">
+  <br>
+  <em>Il tuo codex non è solo.</em>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/oh-my-codex)](https://www.npmjs.com/package/oh-my-codex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+
+> **[Website](https://yeachan-heo.github.io/oh-my-codex-website/)** | **[Documentation](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** | **[CLI Reference](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** | **[Workflows](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** | **[GitHub](https://github.com/Yeachan-Heo/oh-my-codex)** | **[npm](https://www.npmjs.com/package/oh-my-codex)**
+
+Livello di orchestrazione multi-agente per [OpenAI Codex CLI](https://github.com/openai/codex).
+
+## Lingue
+
+- [English](./README.md)
+- [한국어 (Korean)](./README.ko.md)
+- [日本語 (Japanese)](./README.ja.md)
+- [简体中文 (Chinese)](./README.zh.md)
+- [Tiếng Việt (Vietnamese)](./README.vi.md)
+- [Español (Spanish)](./README.es.md)
+- [Português (Portuguese)](./README.pt.md)
+- [Русский (Russian)](./README.ru.md)
+- [Türkçe (Turkish)](./README.tr.md)
+- [Deutsch (German)](./README.de.md)
+- [Français (French)](./README.fr.md)
+- [Italiano (Italian)](./README.it.md)
+
+
+OMX trasforma Codex da un agente a sessione singola in un sistema coordinato con:
+- Role prompts (`/prompts:name`) per agenti specializzati
+- Workflow skills (`$name`) per modalità di esecuzione ripetibili
+- Orchestrazione team in tmux (`omx team`, `$team`)
+- Stato e memoria persistenti tramite server MCP
+
+## Perché OMX
+
+Codex CLI è efficace per compiti diretti. OMX aggiunge struttura per lavori più ampi:
+- Decomposizione ed esecuzione a stadi (`team-plan -> team-prd -> team-exec -> team-verify -> team-fix`)
+- Stato persistente del ciclo di vita delle modalità (`.omx/state/`)
+- Superfici di memoria e notepad per sessioni di lunga durata
+- Controlli operativi per avvio, verifica e annullamento
+
+OMX è un add-on, non un fork. Utilizza i punti di estensione nativi di Codex.
+
+## Requisiti
+
+- macOS o Linux (Windows tramite WSL2)
+- Node.js >= 20
+- Codex CLI installato (`npm install -g @openai/codex`)
+- Autenticazione Codex configurata
+
+## Avvio rapido (3 minuti)
+
+```bash
+npm install -g oh-my-codex
+omx setup
+omx doctor
+```
+
+Profilo di avvio consigliato per ambienti fidati:
+
+```bash
+omx --xhigh --madmax
+```
+
+## Novità nella v0.5.0
+
+- **Setup sensibile allo scope** con `omx setup --scope user|project` per modalità di installazione flessibili.
+- **Routing Spark worker** tramite `--spark` / `--madmax-spark` in modo che i worker del team possano usare `gpt-5.3-codex-spark` senza forzare il modello leader.
+- **Consolidamento del catalogo** — rimossi prompt obsoleti (`deep-executor`, `scientist`) e 9 skill obsolete.
+- **Livelli di verbosità delle notifiche** per un controllo dettagliato dell'output CCNotifier.
+
+## Prima sessione
+
+All'interno di Codex:
+
+```text
+/prompts:architect "analyze current auth boundaries"
+/prompts:executor "implement input validation in login"
+$plan "ship OAuth callback safely"
+$team 3:executor "fix all TypeScript errors"
+```
+
+Dal terminale:
+
+```bash
+omx team 4:executor "parallelize a multi-module refactor"
+omx team status <team-name>
+omx team shutdown <team-name>
+```
+
+## Modello di base
+
+OMX installa e collega questi livelli:
+
+```text
+User
+  -> Codex CLI
+    -> AGENTS.md (cervello dell'orchestrazione)
+    -> ~/.codex/prompts/*.md (catalogo prompt degli agenti)
+    -> ~/.agents/skills/*/SKILL.md (catalogo skill)
+    -> ~/.codex/config.toml (funzionalità, notifiche, MCP)
+    -> .omx/ (stato di esecuzione, memoria, piani, log)
+```
+
+## Comandi principali
+
+```bash
+omx                # Avvia Codex (+ HUD in tmux se disponibile)
+omx setup          # Installa prompt/skill/config per scope + progetto AGENTS.md/.omx
+omx doctor         # Diagnostica installazione/esecuzione
+omx doctor --team  # Diagnostica Team/Swarm
+omx team ...       # Avvia/stato/riprendi/arresta i worker del team tmux
+omx status         # Mostra le modalità attive
+omx cancel         # Annulla le modalità di esecuzione attive
+omx reasoning <mode> # low|medium|high|xhigh
+omx tmux-hook ...  # init|status|validate|test
+omx hooks ...      # init|status|validate|test (workflow estensione plugin)
+omx hud ...        # --watch|--json|--preset
+omx help
+```
+
+## Estensione Hooks (Superficie additiva)
+
+OMX ora include `omx hooks` per lo scaffolding e la validazione dei plugin.
+
+- `omx tmux-hook` resta supportato e invariato.
+- `omx hooks` è additivo e non sostituisce i workflow tmux-hook.
+- I file dei plugin si trovano in `.omx/hooks/*.mjs`.
+- I plugin sono disattivati per impostazione predefinita; abilitali con `OMX_HOOK_PLUGINS=1`.
+
+Consulta `docs/hooks-extension.md` per il workflow completo di estensione e il modello degli eventi.
+
+## Flag di avvio
+
+```bash
+--yolo
+--high
+--xhigh
+--madmax
+--force
+--dry-run
+--verbose
+--scope <user|project>  # solo per setup
+```
+
+`--madmax` corrisponde a Codex `--dangerously-bypass-approvals-and-sandbox`.
+Utilizzare solo in ambienti sandbox fidati/esterni.
+
+### Policy MCP workingDirectory (hardening opzionale)
+
+Per impostazione predefinita, gli strumenti MCP stato/memoria/trace accettano il `workingDirectory` fornito dal chiamante.
+Per limitare questo, imposta una lista di directory root consentite:
+
+```bash
+export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"
+```
+
+Quando impostato, i valori `workingDirectory` al di fuori di queste root vengono rifiutati.
+
+## Controllo Codex-First dei prompt
+
+Per impostazione predefinita, OMX inietta:
+
+```text
+-c model_instructions_file="<cwd>/AGENTS.md"
+```
+
+Questo sovrappone le istruzioni `AGENTS.md` del progetto alle istruzioni di avvio di Codex.
+Estende il comportamento di Codex, ma non sostituisce/aggira le policy di sistema core di Codex.
+
+Controlli:
+
+```bash
+OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx     # disabilita l'iniezione AGENTS.md
+OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx
+```
+
+## Modalità team
+
+Usa la modalità team per lavori ampi che beneficiano di worker paralleli.
+
+Ciclo di vita:
+
+```text
+start -> assign scoped lanes -> monitor -> verify terminal tasks -> shutdown
+```
+
+Comandi operativi:
+
+```bash
+omx team <args>
+omx team status <team-name>
+omx team resume <team-name>
+omx team shutdown <team-name>
+```
+
+Regola importante: non arrestare mentre i task sono ancora `in_progress`, a meno che non si stia abortendo.
+
+### Policy di pulizia Ralph
+
+Quando un team è in esecuzione in modalità ralph (`omx team ralph ...`), la pulizia allo shutdown
+applica una policy dedicata che differisce dal percorso normale:
+
+| Comportamento | Team normale | Team Ralph |
+|---|---|---|
+| Shutdown forzato in caso di errore | Lancia `shutdown_gate_blocked` | Aggira il gate, registra l'evento `ralph_cleanup_policy` |
+| Eliminazione automatica dei branch | Elimina i branch worktree durante il rollback | Preserva i branch (`skipBranchDeletion`) |
+| Logging di completamento | Evento standard `shutdown_gate` | Evento aggiuntivo `ralph_cleanup_summary` con dettaglio dei task |
+
+La policy ralph viene rilevata automaticamente dallo stato della modalità team (`linked_ralph`) o
+può essere passata esplicitamente tramite `omx team shutdown <name> --ralph`.
+
+Selezione CLI worker per i worker del team:
+
+```bash
+OMX_TEAM_WORKER_CLI=auto    # predefinito; usa claude quando worker --model contiene "claude"
+OMX_TEAM_WORKER_CLI=codex   # forza i worker Codex CLI
+OMX_TEAM_WORKER_CLI=claude  # forza i worker Claude CLI
+OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude  # mix CLI per worker (lunghezza=1 o numero di worker)
+OMX_TEAM_AUTO_INTERRUPT_RETRY=0  # opzionale: disabilita il fallback adattivo queue->resend
+```
+
+Note:
+- Gli argomenti di avvio dei worker sono ancora condivisi tramite `OMX_TEAM_WORKER_LAUNCH_ARGS`.
+- `OMX_TEAM_WORKER_CLI_MAP` sovrascrive `OMX_TEAM_WORKER_CLI` per la selezione per singolo worker.
+- L'invio dei trigger usa per impostazione predefinita tentativi adattivi (queue/submit, poi fallback sicuro clear-line+resend quando necessario).
+- In modalità worker Claude, OMX avvia i worker come semplice `claude` (nessun argomento di avvio aggiuntivo) e ignora le sovrascritture esplicite `--model` / `--config` / `--effort` in modo che Claude usi il `settings.json` predefinito.
+
+## Cosa scrive `omx setup`
+
+- `.omx/setup-scope.json` (scope di setup persistito)
+- Installazioni dipendenti dallo scope:
+  - `user`: `~/.codex/prompts/`, `~/.agents/skills/`, `~/.codex/config.toml`, `~/.omx/agents/`
+  - `project`: `./.codex/prompts/`, `./.agents/skills/`, `./.codex/config.toml`, `./.omx/agents/`
+- Comportamento all'avvio: se lo scope persistito è `project`, l'avvio `omx` usa automaticamente `CODEX_HOME=./.codex` (a meno che `CODEX_HOME` non sia già impostato).
+- L'`AGENTS.md` esistente è preservato per impostazione predefinita. Nelle esecuzioni TTY interattive, il setup chiede conferma prima di sovrascrivere; `--force` sovrascrive senza chiedere (i controlli di sicurezza della sessione attiva si applicano comunque).
+- Aggiornamenti `config.toml` (per entrambi gli scope):
+  - `notify = ["node", "..."]`
+  - `model_reasoning_effort = "high"`
+  - `developer_instructions = "..."`
+  - `[features] multi_agent = true, child_agents_md = true`
+  - Voci server MCP (`omx_state`, `omx_memory`, `omx_code_intel`, `omx_trace`)
+  - `[tui] status_line`
+- `AGENTS.md` del progetto
+- Directory di esecuzione `.omx/` e configurazione HUD
+
+## Agenti e Skill
+
+- Prompt: `prompts/*.md` (installati in `~/.codex/prompts/` per `user`, `./.codex/prompts/` per `project`)
+- Skill: `skills/*/SKILL.md` (installati in `~/.agents/skills/` per `user`, `./.agents/skills/` per `project`)
+
+Esempi:
+- Agenti: `architect`, `planner`, `executor`, `debugger`, `verifier`, `security-reviewer`
+- Skill: `autopilot`, `plan`, `team`, `ralph`, `ultrawork`, `cancel`
+
+## Struttura del progetto
+
+```text
+oh-my-codex/
+  bin/omx.js
+  src/
+    cli/
+    team/
+    mcp/
+    hooks/
+    hud/
+    config/
+    modes/
+    notifications/
+    verification/
+  prompts/
+  skills/
+  templates/
+  scripts/
+```
+
+## Sviluppo
+
+```bash
+git clone https://github.com/Yeachan-Heo/oh-my-codex.git
+cd oh-my-codex
+npm install
+npm run build
+npm test
+```
+
+## Documentazione
+
+- **[Documentazione completa](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** — Guida completa
+- **[Riferimento CLI](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** — Tutti i comandi `omx`, flag e strumenti
+- **[Guida alle notifiche](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#notifications)** — Configurazione Discord, Telegram, Slack e webhook
+- **[Workflow consigliati](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** — Catene di skill collaudate per i compiti comuni
+- **[Note di rilascio](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#release-notes)** — Novità di ogni versione
+
+## Note
+
+- Changelog completo: `CHANGELOG.md`
+- Guida alla migrazione (post-v0.4.4 mainline): `docs/migration-mainline-post-v0.4.4.md`
+- Note di copertura e parità: `COVERAGE.md`
+- Workflow estensione hook: `docs/hooks-extension.md`
+- Dettagli setup e contribuzione: `CONTRIBUTING.md`
+
+## Ringraziamenti
+
+Ispirato da [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), adattato per Codex CLI.
+
+## Licenza
+
+MIT