claudeos-core 1.0.7 → 1.2.0

package/README.es.md

@@ -8,7 +8,7 @@ npx claudeos-core init
 
 ClaudeOS-Core lee tu código fuente, extrae cada patrón que encuentra y genera un conjunto completo de Standards, Rules, Skills y Guides adaptados a _tu_ proyecto. Después, cuando le digas a Claude Code "Crea un CRUD para pedidos", generará código que coincide exactamente con tus patrones existentes.
 
-[🇺🇸 English](./README.md) · [🇨🇳 中文](./README.zh-CN.md) · [🇯🇵 日本語](./README.ja.md) · [🇻🇳 Tiếng Việt](./README.vi.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇷🇺 Русский](./README.ru.md) · [🇫🇷 Français](./README.fr.md) · [🇩🇪 Deutsch](./README.de.md) · [🇰🇷 한국어](./README.ko.md)
+[🇺🇸 English](./README.md) · [🇰🇷 한국어](./README.ko.md) · [🇨🇳 中文](./README.zh-CN.md) · [🇯🇵 日本語](./README.ja.md) · [🇻🇳 Tiếng Việt](./README.vi.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇷🇺 Русский](./README.ru.md) · [🇫🇷 Français](./README.fr.md) · [🇩🇪 Deutsch](./README.de.md)
 
 ---
 
@@ -22,7 +22,7 @@ ClaudeOS-Core automatiza todo el proceso:
 
 1. **Escanea** tu proyecto — detecta automáticamente stack, dominios, ORM, base de datos y gestor de paquetes
 2. **Analiza** tu código fuente en profundidad — patrones de controladores, capas de servicio, convenciones de nombrado, manejo de errores, seguridad, testing y más de 50 categorías
-3. **Genera** un ecosistema documental completo — `CLAUDE.md`, Standards (15–17 archivos), Rules, Skills, Guides (9 archivos), Master Plans, documentación de BD y guía MCP
+3. **Genera** un ecosistema documental completo — `CLAUDE.md`, Standards (15–19 archivos), Rules, Skills, Guides (9 archivos), Master Plans, documentación de BD y guía MCP
 4. **Valida** todo — 6 herramientas de verificación integradas garantizan la consistencia
 
 Tiempo total: **5–18 minutos**, según el tamaño del proyecto. Cero configuración manual.
@@ -33,16 +33,53 @@ Tiempo total: **5–18 minutos**, según el tamaño del proyecto. Cero configura
 
 | Stack | Detección | Profundidad de Análisis |
 |---|---|---|
-| **Java / Spring Boot** | `build.gradle`, `pom.xml` | 10 categorías, 59 sub-ítems |
+| **Java / Spring Boot** | `build.gradle`, `pom.xml`, 5 patrones de paquete | 10 categorías, 59 sub-ítems |
+| **Kotlin / Spring Boot** | `build.gradle.kts`, kotlin plugin, `settings.gradle.kts`, CQRS/BFF auto-detect | 12 categorías, 95 sub-ítems |
 | **Node.js / Express / NestJS** | `package.json` | 9 categorías, 57 sub-ítems |
-| **Next.js / React / Vue** | `package.json` (next, react, vue) | 9 categorías, 55 sub-ítems |
+| **Next.js / React / Vue** | `package.json`, `next.config.*`, soporte FSD | 9 categorías, 55 sub-ítems |
 | **Python / Django** | `requirements.txt`, `pyproject.toml` | 10 categorías, 55 sub-ítems |
 | **Python / FastAPI** | `requirements.txt`, `pyproject.toml` | 10 categorías, 58 sub-ítems |
 
-Detección automática: lenguaje y versión, framework y versión, ORM (MyBatis, JPA, Prisma, TypeORM, SQLAlchemy, etc.), base de datos (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestor de paquetes (Gradle, Maven, npm, yarn, pnpm, pip, poetry).
+Detección automática: lenguaje y versión, framework y versión, ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), base de datos (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestor de paquetes (Gradle, Maven, npm, yarn, pnpm, pip, poetry), arquitectura (CQRS, BFF — detectado de nombres de módulos), estructura multi-módulo (desde settings.gradle).
 
 **No necesitas especificar nada. Todo se detecta automáticamente.**
 
+
+### Detección de Dominios Java (5 patrones con fallback)
+
+| Prioridad | Patrón | Estructura | Ejemplo |
+|---|---|---|---|
+| A | Capa primero | `controller/{domain}/` | `controller/user/UserController.java` |
+| B | Dominio primero | `{domain}/controller/` | `user/controller/UserController.java` |
+| D | Prefijo de módulo | `{module}/{domain}/controller/` | `front/member/controller/MemberController.java` |
+| E | DDD/Hexagonal | `{domain}/adapter/in/web/` | `user/adapter/in/web/UserController.java` |
+| C | Plano | `controller/*.java` | `controller/UserController.java` → extrae `user` del nombre de clase |
+
+Los dominios solo con servicios (sin controladores) también se detectan. Se omiten: `common`, `config`, `util`, `front`, `admin`, `v1`, `v2`, etc.
+
+
+### Detección de Dominios Kotlin Multi-Módulo
+
+Para proyectos Kotlin con estructura Gradle multi-módulo (ej: monorepo CQRS):
+
+| Paso | Acción | Ejemplo |
+|---|---|---|
+| 1 | Escanear `settings.gradle.kts` buscando `include()` | Encuentra 14 módulos |
+| 2 | Detectar tipo de módulo por nombre | `reservation-command-server` → tipo: `command` |
+| 3 | Extraer dominio del nombre del módulo | `reservation-command-server` → dominio: `reservation` |
+| 4 | Agrupar mismo dominio entre módulos | `reservation-command-server` + `common-query-server` → 1 dominio |
+| 5 | Detectar arquitectura | Tiene módulos `command` + `query` → CQRS |
+
+Tipos de módulo soportados: `command`, `query`, `bff`, `integration`, `standalone`, `library`. Las bibliotecas compartidas (`shared-lib`, `integration-lib`) se detectan como dominios especiales.
+
+### Detección de Dominios Frontend
+
+- **App Router**: `app/{domain}/page.tsx` (Next.js)
+- **Pages Router**: `pages/{domain}/index.tsx`
+- **FSD (Feature-Sliced Design)**: `features/*/`, `widgets/*/`, `entities/*/`
+- **RSC/Client split**: Detecta patrón `client.tsx`, rastrea separación Server/Client
+- **Config fallback**: Detecta Next.js/Vite/Nuxt desde archivos de configuración (soporte monorepo)
+
 ---
 
 ## Inicio Rápido
@@ -57,16 +94,138 @@ Detección automática: lenguaje y versión, framework y versión, ORM (MyBatis,
 ```bash
 cd /your/project/root
 
-# Opción A: npx (recomendado)
+# Opción A: npx (recomendado — sin instalación)
 npx claudeos-core init
 
-# Opción B: git clone (para desarrollo/contribución)
+# Opción B: instalación global
+npm install -g claudeos-core
+claudeos-core init
+
+# Opción C: devDependency del proyecto
+npm install --save-dev claudeos-core
+npx claudeos-core init
+
+# Opción D: git clone (para desarrollo/contribución)
 git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
 bash claudeos-core-tools/bootstrap.sh
 ```
 
 Eso es todo. Después de 5–18 minutos, toda la documentación estará generada y lista para usar.
 
+### Instalación Manual Paso a Paso
+
+Si deseas control total sobre cada fase, o si el pipeline automatizado falla en algún paso, puedes ejecutar cada etapa manualmente. También es útil para entender cómo funciona ClaudeOS-Core internamente.
+
+#### Step 1: Clonar e instalar dependencias
+
+```bash
+cd /your/project/root
+
+git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
+cd claudeos-core-tools && npm install && cd ..
+```
+
+#### Step 2: Crear estructura de directorios
+
+```bash
+# Rules
+mkdir -p .claude/rules/{00.core,10.backend,20.frontend,30.security-db,40.infra,50.sync}
+
+# Standards
+mkdir -p claudeos-core/standard/{00.core,10.backend-api,20.frontend-ui,30.security-db,40.infra,50.verification,90.optional}
+
+# Skills
+mkdir -p claudeos-core/skills/{00.shared,10.backend-crud/scaffold-crud-feature,20.frontend-page/scaffold-page-feature,50.testing,90.experimental}
+
+# Guide, Plan, Database, MCP, Generated
+mkdir -p claudeos-core/guide/{01.onboarding,02.usage,03.troubleshooting,04.architecture}
+mkdir -p claudeos-core/{plan,database,mcp-guide,generated}
+```
+
+#### Step 3: Ejecutar plan-installer (análisis del proyecto)
+
+Escanea tu proyecto, detecta el stack, encuentra dominios, los divide en grupos y genera prompts.
+
+```bash
+node claudeos-core-tools/plan-installer/index.js
+```
+
+**Salida (`claudeos-core/generated/`):**
+- `project-analysis.json` — stack detectado, dominios, info de frontend
+- `domain-groups.json` — grupos de dominios para Pass 1
+- `pass1-backend-prompt.md` / `pass1-frontend-prompt.md` — prompts de análisis
+- `pass2-prompt.md` — prompt de fusión
+- `pass3-prompt.md` — prompt de generación
+
+Puedes inspeccionar estos archivos para verificar la precisión de la detección antes de continuar.
+
+#### Step 4: Pass 1 — Análisis profundo de código por grupo de dominio
+
+Ejecuta Pass 1 para cada grupo de dominio. Revisa `domain-groups.json` para el número de grupos.
+
+```bash
+# Check groups
+cat claudeos-core/generated/domain-groups.json | node -e "
+  const g = JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+  g.groups.forEach((g,i) => console.log('Group '+(i+1)+': ['+g.domains.join(', ')+'] ('+g.type+', ~'+g.estimatedFiles+' files)'));
+"
+
+# Run Pass 1 for group 1:
+cat claudeos-core/generated/pass1-backend-prompt.md \
+  | sed "s/{{DOMAIN_GROUP}}/user, order, product/g" \
+  | sed "s/{{PASS_NUM}}/1/g" \
+  | claude -p --dangerously-skip-permissions
+
+# For frontend groups, use pass1-frontend-prompt.md instead
+```
+
+**Verificar:** `ls claudeos-core/generated/pass1-*.json` debe mostrar un JSON por grupo.
+
+#### Step 5: Pass 2 — Fusionar resultados de análisis
+
+```bash
+cat claudeos-core/generated/pass2-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Verificar:** `claudeos-core/generated/pass2-merged.json` debe existir con 9+ claves de nivel superior.
+
+#### Step 6: Pass 3 — Generar toda la documentación
+
+```bash
+cat claudeos-core/generated/pass3-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Verificar:** `CLAUDE.md` debe existir en la raíz del proyecto.
+
+#### Step 7: Ejecutar herramientas de verificación
+
+```bash
+# Generar metadatos (requerido antes de otras verificaciones)
+node claudeos-core-tools/manifest-generator/index.js
+
+# Ejecutar todas las verificaciones
+node claudeos-core-tools/health-checker/index.js
+
+# O ejecutar verificaciones individuales:
+node claudeos-core-tools/import-linter/index.js        # @import validation
+node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk
+node claudeos-core-tools/sync-checker/index.js          # Sync status
+node claudeos-core-tools/content-validator/index.js     # Content quality
+node claudeos-core-tools/pass-json-validator/index.js   # JSON format
+```
+
+#### Step 8: Verificar los resultados
+
+```bash
+find .claude claudeos-core -type f | grep -v node_modules | wc -l
+head -30 CLAUDE.md
+ls .claude/rules/*/
+```
+
+> **Consejo:** Si un paso falla, puedes volver a ejecutar solo ese paso. Los resultados de Pass 1/2 se cachean — si `pass1-N.json` o `pass2-merged.json` ya existen, el pipeline automatizado los omite. Elimina el archivo para forzar la re-ejecución.
+
 ### Empieza a Usar
 
 ```
@@ -108,7 +267,7 @@ npx claudeos-core init
 
 ### ¿Por Qué 3 Pasadas?
 
-**Pass 1** es la única pasada que lee tu código fuente. Selecciona archivos representativos por dominio y extrae patrones en 55–59 categorías de análisis (por stack). Para proyectos grandes, Pass 1 se ejecuta múltiples veces — una por grupo de dominios. En proyectos multi-stack (ej: backend Java + frontend React), backend y frontend usan **prompts de análisis diferentes** adaptados a cada stack.
+**Pass 1** es la única pasada que lee tu código fuente. Selecciona archivos representativos por dominio y extrae patrones en 55–95 categorías de análisis (por stack). Para proyectos grandes, Pass 1 se ejecuta múltiples veces — una por grupo de dominios. En proyectos multi-stack (ej: backend Java + frontend React), backend y frontend usan **prompts de análisis diferentes** adaptados a cada stack.
 
 **Pass 2** fusiona todos los resultados de Pass 1 en un análisis unificado: patrones comunes (100% compartidos), patrones mayoritarios (50%+ compartidos), patrones específicos de dominio, anti-patrones por severidad y preocupaciones transversales (nombrado, seguridad, BD, testing, logging, rendimiento).
 
@@ -134,7 +293,7 @@ your-project/
 │
 ├── claudeos-core/                     ← Directorio principal de salida
 │   ├── generated/                     ← JSON de análisis + prompts dinámicos
-│   ├── standard/                      ← Estándares de código (15-17 archivos)
+│   ├── standard/                      ← Estándares de código (15-19 archivos)
 │   ├── skills/                        ← Skills de scaffolding CRUD
 │   ├── guide/                         ← Onboarding, FAQ, troubleshooting (9 archivos)
 │   ├── plan/                          ← Master Plans (backup/restauración)
@@ -228,9 +387,10 @@ npx claudeos-core restore
 
 | | ClaudeOS-Core | SuperClaude | CLAUDE.md Manual | Skills Genéricos |
 |---|---|---|---|---|
-| **Lee tu código** | ✅ Análisis profundo (55–59 categorías) | ❌ Inyección de comportamiento | ❌ Escritura manual | ❌ Plantillas predefinidas |
+| **Lee tu código** | ✅ Análisis profundo (55–95 categorías) | ❌ Inyección de comportamiento | ❌ Escritura manual | ❌ Plantillas predefinidas |
 | **Salida específica del proyecto** | ✅ Cada archivo refleja tus patrones | ❌ Comandos genéricos | Parcial | ❌ Talla única |
 | **Multi-stack** | ✅ Auto-detección + análisis separado | ❌ Agnóstico al stack | Manual | Variable |
+| **Kotlin + CQRS/BFF** | ✅ Multi-module, Command/Query split | ❌ | ❌ | ❌ |
 | **Auto-verificación** | ✅ 6 herramientas de validación | ❌ | ❌ | ❌ |
 | **Backup / Restauración** | ✅ Sistema Master Plan | ❌ | ❌ | ❌ |
 | **Tiempo de configuración** | ~5–18min (automático) | ~5min (config manual) | Horas–Días | ~5min |
@@ -254,6 +414,15 @@ Totalmente soportado. ClaudeOS-Core auto-detecta ambos stacks, etiqueta dominios
 **P: ¿Qué pasa al re-ejecutar?**
 Pass 1/2 se omiten si su JSON ya existe. Pass 3 siempre se re-ejecuta. Las versiones anteriores pueden restaurarse desde los Master Plans.
 
+**P: ¿Soporta Kotlin?**
+Sí. ClaudeOS-Core detecta automáticamente Kotlin desde `build.gradle.kts` o el plugin kotlin en `build.gradle`. Utiliza una plantilla dedicada `kotlin-spring` con análisis específico de Kotlin (data classes, sealed classes, coroutines, extension functions, MockK, etc.).
+
+**P: ¿Qué hay de la arquitectura CQRS / BFF?**
+Totalmente soportado para proyectos multi-módulo de Kotlin. ClaudeOS-Core lee `settings.gradle.kts`, detecta tipos de módulos (command, query, bff, integration) de los nombres, y agrupa el mismo dominio entre módulos Command/Query. Los estándares generados incluyen reglas separadas para command controllers vs query controllers, patrones BFF/Feign y convenciones de comunicación entre módulos.
+
+**P: ¿Qué hay de los monorepos multi-módulo de Gradle?**
+ClaudeOS-Core escanea todos los submódulos (`**/src/main/kotlin/**/*.kt`) sin importar la profundidad de anidamiento. Los tipos de módulos se infieren de las convenciones de nombres (ej: `reservation-command-server` → dominio: `reservation`, tipo: `command`). Las bibliotecas compartidas (`shared-lib`, `integration-lib`) también se detectan.
+
 ---
 
 ## Estructura de Plantillas
@@ -262,6 +431,7 @@ Pass 1/2 se omiten si su JSON ya existe. Pass 3 siempre se re-ejecuta. Las versi
 pass-prompts/templates/
 ├── common/                  # Encabezado/pie compartido
 ├── java-spring/             # Java / Spring Boot
+├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
 ├── node-express/            # Node.js / Express / NestJS
 ├── node-nextjs/             # Next.js / React / Vue
 ├── python-django/           # Python / Django (DRF)
@@ -313,7 +483,13 @@ my-monorepo/                    ← No ejecutes aquí (la raíz no tiene deps de
 
 **"npm install failed"** — La versión de Node.js puede ser demasiado baja. Se requiere v18+.
 
-**"0 domains detected"** — La estructura de tu proyecto puede ser no estándar. Consulta los patrones de detección en la [documentación en coreano](./README.ko.md#-문제-해결--troubleshooting) para tu stack.
+**"0 domains detected"** — La estructura de tu proyecto puede ser no estándar. Consulta los patrones de detección en la [documentación en coreano](./README.ko.md#트러블슈팅) para tu stack.
+
+**"0 dominios detectados" en proyecto Kotlin** — Asegúrate de que `build.gradle.kts` (o `build.gradle` con plugin kotlin) exista en la raíz, y los archivos fuente estén bajo `**/src/main/kotlin/`. Para proyectos multi-módulo, `settings.gradle.kts` debe contener sentencias `include()`. Los proyectos Kotlin de módulo único (sin `settings.gradle`) también son compatibles — los dominios se extraen de la estructura de paquetes/clases bajo `src/main/kotlin/`.
+
+**"Lenguaje detectado como java en vez de kotlin"** — ClaudeOS-Core primero verifica el `build.gradle(.kts)` raíz, luego los archivos build de submódulos. Asegúrate de que al menos uno contenga `kotlin("jvm")` o `org.jetbrains.kotlin`.
+
+**"CQRS no detectado"** — La detección de arquitectura depende de que los nombres de módulos contengan las palabras `command` y `query`. Si tus módulos usan nombres diferentes, puedes ajustar manualmente los prompts generados.
 
 ---
 

package/README.fr.md

@@ -8,7 +8,7 @@ npx claudeos-core init
 
 ClaudeOS-Core lit votre codebase, extrait chaque pattern qu'il trouve et génère un ensemble complet de Standards, Rules, Skills et Guides adaptés à _votre_ projet. Ensuite, quand vous dites à Claude Code « Crée un CRUD pour les commandes », il produit du code qui correspond exactement à vos patterns existants.
 
-[🇺🇸 English](./README.md) · [🇨🇳 中文](./README.zh-CN.md) · [🇯🇵 日本語](./README.ja.md) · [🇪🇸 Español](./README.es.md) · [🇻🇳 Tiếng Việt](./README.vi.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇷🇺 Русский](./README.ru.md) · [🇩🇪 Deutsch](./README.de.md) · [🇰🇷 한국어](./README.ko.md)
+[🇺🇸 English](./README.md) · [🇰🇷 한국어](./README.ko.md) · [🇨🇳 中文](./README.zh-CN.md) · [🇯🇵 日本語](./README.ja.md) · [🇪🇸 Español](./README.es.md) · [🇻🇳 Tiếng Việt](./README.vi.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇷🇺 Русский](./README.ru.md) · [🇩🇪 Deutsch](./README.de.md)
 
 ---
 
@@ -22,7 +22,7 @@ ClaudeOS-Core automatise l'ensemble du processus :
 
 1. **Scanne** votre projet — détecte automatiquement le stack, les domaines, l'ORM, la base de données et le gestionnaire de paquets
 2. **Analyse en profondeur** votre code source — patterns de contrôleurs, couches de service, conventions de nommage, gestion des erreurs, sécurité, tests et plus de 50 catégories
-3. **Génère** un écosystème documentaire complet — `CLAUDE.md`, Standards (15–17 fichiers), Rules, Skills, Guides (9 fichiers), Master Plans, documentation BD et guide MCP
+3. **Génère** un écosystème documentaire complet — `CLAUDE.md`, Standards (15–19 fichiers), Rules, Skills, Guides (9 fichiers), Master Plans, documentation BD et guide MCP
 4. **Valide** tout — 6 outils de vérification intégrés garantissent la cohérence
 
 Temps total : **5–18 minutes**, selon la taille du projet. Zéro configuration manuelle.
@@ -33,16 +33,53 @@ Temps total : **5–18 minutes**, selon la taille du projet. Zéro configuration
 
 | Stack | Détection | Profondeur d'Analyse |
 |---|---|---|
-| **Java / Spring Boot** | `build.gradle`, `pom.xml` | 10 catégories, 59 sous-éléments |
+| **Java / Spring Boot** | `build.gradle`, `pom.xml`, 5 patterns de paquets | 10 catégories, 59 sous-éléments |
+| **Kotlin / Spring Boot** | `build.gradle.kts`, kotlin plugin, `settings.gradle.kts`, CQRS/BFF auto-detect | 12 catégories, 95 sous-éléments |
 | **Node.js / Express / NestJS** | `package.json` | 9 catégories, 57 sous-éléments |
-| **Next.js / React / Vue** | `package.json` (next, react, vue) | 9 catégories, 55 sous-éléments |
+| **Next.js / React / Vue** | `package.json`, `next.config.*`, support FSD | 9 catégories, 55 sous-éléments |
 | **Python / Django** | `requirements.txt`, `pyproject.toml` | 10 catégories, 55 sous-éléments |
 | **Python / FastAPI** | `requirements.txt`, `pyproject.toml` | 10 catégories, 58 sous-éléments |
 
-Détection automatique : langage et version, framework et version, ORM (MyBatis, JPA, Prisma, TypeORM, SQLAlchemy, etc.), base de données (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestionnaire de paquets (Gradle, Maven, npm, yarn, pnpm, pip, poetry).
+Détection automatique : langage et version, framework et version, ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), base de données (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestionnaire de paquets (Gradle, Maven, npm, yarn, pnpm, pip, poetry), architecture (CQRS, BFF — détecté à partir des noms de modules), structure multi-module (depuis settings.gradle).
 
 **Vous n'avez rien à spécifier. Tout est détecté automatiquement.**
 
+
+### Détection des Domaines Java (5 patterns avec fallback)
+
+| Priorité | Pattern | Structure | Exemple |
+|---|---|---|---|
+| A | Couche d'abord | `controller/{domain}/` | `controller/user/UserController.java` |
+| B | Domaine d'abord | `{domain}/controller/` | `user/controller/UserController.java` |
+| D | Préfixe module | `{module}/{domain}/controller/` | `front/member/controller/MemberController.java` |
+| E | DDD/Hexagonal | `{domain}/adapter/in/web/` | `user/adapter/in/web/UserController.java` |
+| C | Plat | `controller/*.java` | `controller/UserController.java` → extrait `user` du nom de classe |
+
+Les domaines sans contrôleurs (service uniquement) sont aussi détectés. Ignorés : `common`, `config`, `util`, `front`, `admin`, `v1`, `v2`, etc.
+
+
+### Détection des domaines Kotlin multi-modules
+
+Pour les projets Kotlin avec structure Gradle multi-modules (ex : monorepo CQRS) :
+
+| Étape | Action | Exemple |
+|---|---|---|
+| 1 | Scanner `settings.gradle.kts` pour les `include()` | 14 modules trouvés |
+| 2 | Détecter le type de module par son nom | `reservation-command-server` → type : `command` |
+| 3 | Extraire le domaine du nom du module | `reservation-command-server` → domaine : `reservation` |
+| 4 | Regrouper le même domaine entre modules | `reservation-command-server` + `common-query-server` → 1 domaine |
+| 5 | Détecter l'architecture | Modules `command` + `query` présents → CQRS |
+
+Types de modules supportés : `command`, `query`, `bff`, `integration`, `standalone`, `library`. Les bibliothèques partagées (`shared-lib`, `integration-lib`) sont détectées comme domaines spéciaux.
+
+### Détection des Domaines Frontend
+
+- **App Router** : `app/{domain}/page.tsx` (Next.js)
+- **Pages Router** : `pages/{domain}/index.tsx`
+- **FSD (Feature-Sliced Design)** : `features/*/`, `widgets/*/`, `entities/*/`
+- **RSC/Client split** : Détecte le pattern `client.tsx`, suit la séparation Server/Client
+- **Fallback config** : Détecte Next.js/Vite/Nuxt depuis les fichiers de config (support monorepo)
+
 ---
 
 ## Démarrage Rapide
@@ -57,16 +94,138 @@ Détection automatique : langage et version, framework et version, ORM (MyBatis,
 ```bash
 cd /your/project/root
 
-# Option A : npx (recommandé)
+# Option A : npx (recommandé — aucune installation requise)
 npx claudeos-core init
 
-# Option B : git clone (pour développement/contribution)
+# Option B : installation globale
+npm install -g claudeos-core
+claudeos-core init
+
+# Option C : devDependency du projet
+npm install --save-dev claudeos-core
+npx claudeos-core init
+
+# Option D : git clone (pour développement/contribution)
 git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
 bash claudeos-core-tools/bootstrap.sh
 ```
 
 C'est tout. Après 5–18 minutes, toute la documentation est générée et prête à l'emploi.
 
+### Installation Manuelle Étape par Étape
+
+Si vous souhaitez un contrôle total sur chaque phase — ou si le pipeline automatisé échoue à une étape — vous pouvez exécuter chaque étape manuellement. C'est également utile pour comprendre le fonctionnement interne de ClaudeOS-Core.
+
+#### Step 1 : Cloner et installer les dépendances
+
+```bash
+cd /your/project/root
+
+git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
+cd claudeos-core-tools && npm install && cd ..
+```
+
+#### Step 2 : Créer la structure des répertoires
+
+```bash
+# Rules
+mkdir -p .claude/rules/{00.core,10.backend,20.frontend,30.security-db,40.infra,50.sync}
+
+# Standards
+mkdir -p claudeos-core/standard/{00.core,10.backend-api,20.frontend-ui,30.security-db,40.infra,50.verification,90.optional}
+
+# Skills
+mkdir -p claudeos-core/skills/{00.shared,10.backend-crud/scaffold-crud-feature,20.frontend-page/scaffold-page-feature,50.testing,90.experimental}
+
+# Guide, Plan, Database, MCP, Generated
+mkdir -p claudeos-core/guide/{01.onboarding,02.usage,03.troubleshooting,04.architecture}
+mkdir -p claudeos-core/{plan,database,mcp-guide,generated}
+```
+
+#### Step 3 : Exécuter plan-installer (analyse du projet)
+
+Scanne votre projet, détecte le stack, trouve les domaines, les divise en groupes et génère les prompts.
+
+```bash
+node claudeos-core-tools/plan-installer/index.js
+```
+
+**Sortie (`claudeos-core/generated/`) :**
+- `project-analysis.json` — stack détecté, domaines, info frontend
+- `domain-groups.json` — groupes de domaines pour le Pass 1
+- `pass1-backend-prompt.md` / `pass1-frontend-prompt.md` — prompts d'analyse
+- `pass2-prompt.md` — prompt de fusion
+- `pass3-prompt.md` — prompt de génération
+
+Vous pouvez inspecter ces fichiers pour vérifier la précision de la détection avant de continuer.
+
+#### Step 4 : Pass 1 — Analyse approfondie du code par groupe de domaines
+
+Exécutez Pass 1 pour chaque groupe de domaines. Vérifiez `domain-groups.json` pour le nombre de groupes.
+
+```bash
+# Check groups
+cat claudeos-core/generated/domain-groups.json | node -e "
+  const g = JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+  g.groups.forEach((g,i) => console.log('Group '+(i+1)+': ['+g.domains.join(', ')+'] ('+g.type+', ~'+g.estimatedFiles+' files)'));
+"
+
+# Run Pass 1 for group 1:
+cat claudeos-core/generated/pass1-backend-prompt.md \
+  | sed "s/{{DOMAIN_GROUP}}/user, order, product/g" \
+  | sed "s/{{PASS_NUM}}/1/g" \
+  | claude -p --dangerously-skip-permissions
+
+# For frontend groups, use pass1-frontend-prompt.md instead
+```
+
+**Vérifier :** `ls claudeos-core/generated/pass1-*.json` doit afficher un JSON par groupe.
+
+#### Step 5 : Pass 2 — Fusion des résultats d'analyse
+
+```bash
+cat claudeos-core/generated/pass2-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Vérifier :** `claudeos-core/generated/pass2-merged.json` doit exister avec 9+ clés de niveau supérieur.
+
+#### Step 6 : Pass 3 — Générer toute la documentation
+
+```bash
+cat claudeos-core/generated/pass3-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Vérifier :** `CLAUDE.md` doit exister à la racine du projet.
+
+#### Step 7 : Exécuter les outils de vérification
+
+```bash
+# Générer les métadonnées (requis avant les autres vérifications)
+node claudeos-core-tools/manifest-generator/index.js
+
+# Exécuter toutes les vérifications
+node claudeos-core-tools/health-checker/index.js
+
+# Ou exécuter les vérifications individuellement :
+node claudeos-core-tools/import-linter/index.js        # @import validation
+node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk
+node claudeos-core-tools/sync-checker/index.js          # Sync status
+node claudeos-core-tools/content-validator/index.js     # Content quality
+node claudeos-core-tools/pass-json-validator/index.js   # JSON format
+```
+
+#### Step 8 : Vérifier les résultats
+
+```bash
+find .claude claudeos-core -type f | grep -v node_modules | wc -l
+head -30 CLAUDE.md
+ls .claude/rules/*/
+```
+
+> **Conseil :** Si une étape échoue, vous pouvez relancer uniquement cette étape. Les résultats Pass 1/2 sont mis en cache — si `pass1-N.json` ou `pass2-merged.json` existe déjà, le pipeline automatisé les ignore. Supprimez le fichier pour forcer la ré-exécution.
+
 ### Commencez à Utiliser
 
 ```
@@ -108,7 +267,7 @@ npx claudeos-core init
 
 ### Pourquoi 3 Pass ?
 
-**Pass 1** est le seul pass qui lit votre code source. Il sélectionne des fichiers représentatifs par domaine et extrait les patterns sur 55–59 catégories d'analyse (par stack). Pour les grands projets, Pass 1 s'exécute plusieurs fois — une par groupe de domaines. Dans les projets multi-stack (ex : backend Java + frontend React), backend et frontend utilisent **des prompts d'analyse différents** adaptés à chaque stack.
+**Pass 1** est le seul pass qui lit votre code source. Il sélectionne des fichiers représentatifs par domaine et extrait les patterns sur 55–95 catégories d'analyse (par stack). Pour les grands projets, Pass 1 s'exécute plusieurs fois — une par groupe de domaines. Dans les projets multi-stack (ex : backend Java + frontend React), backend et frontend utilisent **des prompts d'analyse différents** adaptés à chaque stack.
 
 **Pass 2** fusionne tous les résultats de Pass 1 en une analyse unifiée : patterns communs (100% partagés), patterns majoritaires (50%+ partagés), patterns spécifiques au domaine, anti-patterns par sévérité et préoccupations transversales (nommage, sécurité, BD, tests, journalisation, performance).
 
@@ -134,7 +293,7 @@ your-project/
 │
 ├── claudeos-core/                     ← Répertoire principal de sortie
 │   ├── generated/                     ← JSON d'analyse + prompts dynamiques
-│   ├── standard/                      ← Standards de code (15-17 fichiers)
+│   ├── standard/                      ← Standards de code (15-19 fichiers)
 │   ├── skills/                        ← Skills de scaffolding CRUD
 │   ├── guide/                         ← Onboarding, FAQ, dépannage (9 fichiers)
 │   ├── plan/                          ← Master Plans (sauvegarde/restauration)
@@ -228,9 +387,10 @@ npx claudeos-core restore
 
 | | ClaudeOS-Core | SuperClaude | CLAUDE.md Manuel | Skills Génériques |
 |---|---|---|---|---|
-| **Lit votre code** | ✅ Analyse approfondie (55–59 catégories) | ❌ Injection de comportement | ❌ Écriture manuelle | ❌ Templates prédéfinis |
+| **Lit votre code** | ✅ Analyse approfondie (55–95 catégories) | ❌ Injection de comportement | ❌ Écriture manuelle | ❌ Templates prédéfinis |
 | **Sortie spécifique au projet** | ✅ Chaque fichier reflète vos patterns | ❌ Commandes génériques | Partiel | ❌ Taille unique |
 | **Multi-stack** | ✅ Auto-détection + analyse séparée | ❌ Agnostique au stack | Manuel | Variable |
+| **Kotlin + CQRS/BFF** | ✅ Multi-module, Command/Query split | ❌ | ❌ | ❌ |
 | **Auto-vérification** | ✅ 6 outils de validation | ❌ | ❌ | ❌ |
 | **Sauvegarde / Restauration** | ✅ Système Master Plan | ❌ | ❌ | ❌ |
 | **Temps de configuration** | ~5–18 min (automatique) | ~5 min (config manuelle) | Heures–Jours | ~5 min |
@@ -254,6 +414,15 @@ Entièrement supporté. ClaudeOS-Core auto-détecte les deux stacks, étiquette
 **Q : Que se passe-t-il lors d'une ré-exécution ?**
 Pass 1/2 sont ignorés si leur JSON existe déjà. Pass 3 est toujours ré-exécuté. Les versions précédentes peuvent être restaurées depuis les Master Plans.
 
+**Q : Kotlin est-il supporté ?**
+Oui. ClaudeOS-Core détecte automatiquement Kotlin à partir de `build.gradle.kts` ou du plugin kotlin dans `build.gradle`. Il utilise un template dédié `kotlin-spring` avec une analyse spécifique à Kotlin (data classes, sealed classes, coroutines, fonctions d'extension, MockK, etc.).
+
+**Q : Qu'en est-il de l'architecture CQRS / BFF ?**
+Entièrement supporté pour les projets Kotlin multi-modules. ClaudeOS-Core lit `settings.gradle.kts`, détecte les types de modules (command, query, bff, integration) à partir de leurs noms, et regroupe le même domaine à travers les modules Command/Query. Les standards générés incluent des règles séparées pour les command controllers vs query controllers, les patterns BFF/Feign et les conventions de communication inter-modules.
+
+**Q : Qu'en est-il des monorepos multi-modules Gradle ?**
+ClaudeOS-Core analyse tous les sous-modules (`**/src/main/kotlin/**/*.kt`) quelle que soit la profondeur d'imbrication. Les types de modules sont déduits des conventions de nommage (ex : `reservation-command-server` → domaine : `reservation`, type : `command`). Les bibliothèques partagées (`shared-lib`, `integration-lib`) sont également détectées.
+
 ---
 
 ## Structure des Templates
@@ -262,6 +431,7 @@ Pass 1/2 sont ignorés si leur JSON existe déjà. Pass 3 est toujours ré-exéc
 pass-prompts/templates/
 ├── common/                  # En-tête/pied de page partagés
 ├── java-spring/             # Java / Spring Boot
+├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
 ├── node-express/            # Node.js / Express / NestJS
 ├── node-nextjs/             # Next.js / React / Vue
 ├── python-django/           # Python / Django (DRF)
@@ -313,7 +483,13 @@ my-monorepo/                    ← Ne pas exécuter ici (la racine n'a pas de d
 
 **"npm install failed"** — La version de Node.js peut être trop ancienne. v18+ requis.
 
-**"0 domains detected"** — La structure de votre projet peut être non standard. Consultez les patterns de détection dans la [documentation coréenne](./README.ko.md#-문제-해결--troubleshooting) pour votre stack.
+**"0 domains detected"** — La structure de votre projet peut être non standard. Consultez les patterns de détection dans la [documentation coréenne](./README.ko.md#트러블슈팅) pour votre stack.
+
+**« 0 domaines détectés » sur un projet Kotlin** — Vérifiez que `build.gradle.kts` (ou `build.gradle` avec le plugin kotlin) existe à la racine, et que les fichiers source sont sous `**/src/main/kotlin/`. Pour les projets multi-modules, `settings.gradle.kts` doit contenir des instructions `include()`. Les projets Kotlin mono-module (sans `settings.gradle`) sont également pris en charge — les domaines sont extraits de la structure des packages/classes sous `src/main/kotlin/`.
+
+**« Langage détecté comme java au lieu de kotlin »** — ClaudeOS-Core vérifie d'abord le `build.gradle(.kts)` racine, puis les fichiers build des sous-modules. Assurez-vous qu'au moins un contient `kotlin("jvm")` ou `org.jetbrains.kotlin`.
+
+**« CQRS non détecté »** — La détection d'architecture repose sur la présence des mots-clés `command` et `query` dans les noms de modules. Si vos modules utilisent des noms différents, vous pouvez ajuster manuellement les prompts générés.
 
 ---