claudeos-core 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [1.4.0] — 2026-04-04
+
+### Fixed
+- **Arrow key compatibility** — Added application mode escape sequences (`\x1bOA`/`\x1bOB`) for terminals that use SS3 mode (Git Bash/mintty, tmux, screen); previously only normal mode (`\x1b[A`/`\x1b[B`) was handled
+- **`setRawMode` crash prevention** — Wrapped `setRawMode(true)` in try-catch; falls back to number input if raw mode is unsupported (e.g., some Windows terminal emulators)
+- **React/CRA/Vite/RN frontend domain detection** — Added Fallback C (`**/components/*/`) and Fallback D (deep `**/views/*/`, `**/screens/*/`, `**/containers/*/`, `**/pages/*/`, `**/routes/*/`, `**/modules/*/`, `**/domains/*/`) for pure React projects without Next.js App Router; previously only `{src/,}components/*/` (1-depth) was scanned, causing 0 domains for projects with deep component structures (e.g., `src/desktop/app/components/order/`)
+- **Vue `.vue` file detection** — Added `.vue` extension to all frontend domain scanning globs (primary, FSD, components, Fallback B/C/D); previously `.vue` was only included in statistics globs but not in domain detection, causing 0 domains for Vue/Nuxt projects
+- **`setRawMode` fallback UX** — Added "Generated files will be written in this language" description text to setRawMode fallback path (was missing, non-TTY and arrow-key paths had it)
+- **Fallback C/D glob performance** — Added `.git`, `vendor`, `__pycache__`, `coverage` to ignore list (prevents scanning non-source directories in large repos)
+- **Fallback D domain source tracking** — Domain entries now include `sources` field recording which directory pattern(s) matched (e.g., `["views", "routes"]`), preventing silent conflation
+- **`plan-validator` / `sync-checker` path traversal** — Changed `startsWith(ROOT + sep)` to also allow `=== ROOT` (fixes edge case where ROOT-level files like `CLAUDE.md` could be rejected on Windows)
+- **`content-validator` Kotlin code block check** — Core standard files (`00.core/02.`, `00.core/03.`) downgraded from warning to silent skip (may legitimately lack `\`\`\`kotlin` blocks in multi-stack projects)
+- **`manifest-generator` sync-map completeness** — Code-block format plan files (e.g., `21.sync-rules-master.md`) now included in `sync-map.json`; previously only `<file>` block format plans were extracted, causing sync-checker to report false "unregistered" entries
+
+### Changed
+- **Language selector hint** — Added `1-0 Jump` and `ESC Cancel` to the interactive selector hint line (`↑↓ Move  1-0 Jump  Enter Select  ESC Cancel`); users can now discover number key shortcuts without reading docs
+- **`bootstrap.sh` completion box** — Added `Output language:` line (was missing, cli.js had it); changed verify command from `node claudeos-core-tools/health-checker/index.js` to `npx claudeos-core health` (matches cli.js)
+- **All 10 READMEs** — Language selector example updated to match new hint text; description text changed from "arrow keys" to "arrow keys or number keys"
+- **`selectTemplates` pure frontend fix** — TypeScript/JavaScript/Python language-only fallback no longer assigns a backend template when `stack.framework` is absent; pure frontend projects (CRA, Vite, Vue CLI) now correctly get `backend: null` instead of `node-express`
+- **`stack-detector` NestJS priority** — NestJS checked before Express (NestJS is more specific; NestJS projects always include express as a dependency); both now use `!stack.framework` guard for order-independence
+- **`domain-grouper` dead code removal** — Removed unreachable `if (!templates.backend && templates.frontend)` block and orphaned "Dynamic prompt generation" comment
+- **`cli.js` `countFiles` resilience** — `realpathSync` wrapped in try-catch to handle Windows junction points that throw
+- **`bootstrap.sh` prerequisites** — Added `perl` to header comment prerequisites list
+
+## [1.3.1] — 2026-04-03
+
+### Changed
+- **Context efficiency: rules paths scoping** — `40.infra/*` and `50.sync/*` rules now use scoped `paths:` frontmatter instead of `["**/*"]`; infra rules load only for config/infra files, sync rules load only for claudeos-core files (5 stacks; python-django infra keeps `["**/*"]` due to .py settings)
+- **Context efficiency: standard reference distribution** — `00.standard-reference.md` changed from "MUST Read ALL" to "Standard Documents Directory — Read ONLY relevant"; each rule file now ends with `## Reference` section linking to its corresponding standard
+- **content-validator** — Removed `50.sync` exemption from frontmatter validation; all rules now checked equally; updated comment and warning message to reflect scoped paths
+- **prompt-generator** — Removed duplicate `pass1-prompt.md` generation (backward-compat fallback no longer needed; `pass1-{type}-prompt.md` is always generated)
+- **Pass 1 templates** (all 6 stacks) — "Do not create files" → "Do not create or modify source files" (clarifies that saving analysis JSON is allowed)
+- **All 10 READMEs** — "How Claude Code Uses Your Documentation" section updated: auto-load table now shows per-category paths, standard reading explained as on-demand via `## Reference` links
+- **Pass 3 CRITICAL directive: Code Example Accuracy** (all 6 stacks) — Rules/standards code examples must use EXACT method names from pass2-merged.json; prevents hallucination of API names (e.g., `ok()` instead of `success()`)
+
 ## [1.3.0] — 2026-04-03
 
 ### Added

package/README.de.md

@@ -1,6 +1,6 @@
 # ClaudeOS-Core
 
-**Ein Befehl. Ihre gesamte Claude Code Dokumentation — automatisch aus Ihrem Quellcode generiert.**
+**Das einzige Tool, das zuerst Ihren Quellcode liest, Stack und Patterns mit deterministischer Analyse bestätigt und dann Claude Code Regeln generiert, die exakt auf Ihr Projekt zugeschnitten sind.**
 
 ```bash
 npx claudeos-core init
@@ -12,20 +12,50 @@ ClaudeOS-Core liest Ihre Codebasis, extrahiert jedes Muster und generiert einen
 
 ---
 
-## Das Problem
+## Warum ClaudeOS-Core?
 
-Claude Code ist leistungsstark, aber es kennt nicht die Konventionen _Ihres_ Projekts. Das manuelle Schreiben einer `CLAUDE.md`, dutzender Regeln und Scaffolding-Skills dauert Stunden — und sie veralten, sobald sich Ihre Codebasis weiterentwickelt.
+> Mensch beschreibt das Projekt → LLM generiert Dokumentation
 
-## Die Lösung
+ClaudeOS-Core:
 
-ClaudeOS-Core automatisiert den gesamten Prozess:
+> Code analysiert Quellcode → Code baut maßgeschneiderten Prompt → LLM generiert Dokumentation → Code verifiziert Output
 
-1. **Scannt** Ihr Projekt — erkennt automatisch Stack, Domänen, ORM, Datenbank, Paketmanager
-2. **Analysiert** Ihren Quellcode tiefgehend — Controller-Muster, Service-Schichten, Namenskonventionen, Fehlerbehandlung, Sicherheit, Tests und 50+ Kategorien
-3. **Generiert** ein vollständiges Dokumentationsökosystem — `CLAUDE.md`, Standards (15–19 Dateien), Rules, Skills, Guides (9 Dateien), Master Plans, DB-Dokumentation und MCP-Leitfaden
-4. **Validiert** alles — 5 integrierte Verifizierungstools gewährleisten Konsistenz
+### Das Kernproblem: LLMs raten. Code bestätigt.
 
-Gesamtzeit: **5–18 Minuten**, abhängig von der Projektgröße. Null manuelle Konfiguration.
+Wenn Sie Claude bitten, "dieses Projekt zu analysieren", **rät** es Ihren Stack, ORM, Domänenstruktur.
+
+**ClaudeOS-Core rät nicht.** Claude Node.js:
+
+- `build.gradle` / `package.json` / `pyproject.toml` → **confirmed**
+- directory scan → **confirmed**
+- Java 5 patterns, Kotlin CQRS/BFF, Next.js App Router/FSD → **classified**
+- domain groups → **split**
+- stack-specific prompt → **assembled**
+
+### Das Ergebnis
+
+Andere Tools erzeugen "allgemein gute" Dokumentation.
+ClaudeOS-Core erzeugt Dokumentation, die weiß, dass Ihr Projekt `ApiResponse.ok()` verwendet (nicht `ResponseEntity.success()`), dass Ihre MyBatis XML Mapper in `src/main/resources/mapper/{domain}/` liegen — weil es Ihren tatsächlichen Code gelesen hat.
+
+### Before & After
+
+**Ohne ClaudeOS-Core**:
+```
+❌ JPA repository (MyBatis)
+❌ ResponseEntity.success() (ApiResponse.ok())
+❌ order/controller/ (controller/order/)
+→ 20 min fix per file
+```
+
+**Mit ClaudeOS-Core**:
+```
+✅ MyBatis mapper + XML (build.gradle)
+✅ ApiResponse.ok() (source code)
+✅ controller/order/ (Pattern A)
+→ immediate match
+```
+
+Dieser Unterschied summiert sich. 10 Aufgaben/Tag × 20 Minuten gespart = **über 3 Stunden/Tag**.
 
 ---
 
@@ -79,6 +109,7 @@ Unterstützte Modultypen: `command`, `query`, `bff`, `integration`, `standalone`
 - **FSD (Feature-Sliced Design)**: `features/*/`, `widgets/*/`, `entities/*/`
 - **RSC/Client-Split**: Erkennt `client.tsx`-Muster, verfolgt Server/Client-Trennung
 - **Config-Fallback**: Erkennt Next.js/Vite/Nuxt aus Config-Dateien (Monorepo-Unterstützung)
+- **Tiefe Verzeichnis-Fallback**: Für React/CRA/Vite/Vue/RN-Projekte scannt `**/components/*/`, `**/views/*/`, `**/screens/*/`, `**/containers/*/`, `**/pages/*/`, `**/routes/*/`, `**/modules/*/`, `**/domains/*/` in beliebiger Tiefe
 
 ---
 
@@ -117,7 +148,7 @@ bash claudeos-core-tools/bootstrap.sh
 
 ### Ausgabesprache (10 Sprachen)
 
-Wenn Sie `init` ohne `--lang` ausführen, erscheint ein interaktiver Selektor mit Pfeiltasten:
+Wenn Sie `init` ohne `--lang` ausführen, erscheint ein interaktiver Selektor (Pfeiltasten oder Zifferntasten):
 
 ```
 ╔══════════════════════════════════════════════════╗
@@ -131,7 +162,7 @@ Wenn Sie `init` ohne `--lang` ausführen, erscheint ein interaktiver Selektor mi
      ...
   ❯ 10. de     — Deutsch (German)
 
-  ↑↓ Move  ↵ Select
+  ↑↓ Move  1-0 Jump  Enter Select  ESC Cancel
 ```
 
 Die Beschreibung wechselt beim Navigieren in die entsprechende Sprache. Um den Selektor zu überspringen:
@@ -386,16 +417,21 @@ So liest Claude Code die von ClaudeOS-Core generierte Dokumentation tatsächlich
 | Datei | Wann | Garantiert |
 |---|---|---|
 | `CLAUDE.md` | Bei jedem Gesprächsstart | Immer |
-| `.claude/rules/*.md` | Beim Bearbeiten von Dateien (via `paths: ["**/*"]`) | Immer |
-| `.claude/rules/00.core/00.standard-reference.md` | ↑ Oben enthalten | Immer |
+| `.claude/rules/00.core/*` | Beim Bearbeiten von Dateien (`paths: ["**/*"]`) | Immer |
+| `.claude/rules/10.backend/*` | Beim Bearbeiten von Dateien (`paths: ["**/*"]`) | Immer |
+| `.claude/rules/30.security-db/*` | Beim Bearbeiten von Dateien (`paths: ["**/*"]`) | Immer |
+| `.claude/rules/40.infra/*` | Nur bei Config/Infra-Dateien (eingeschränkte Paths) | Bedingt |
+| `.claude/rules/50.sync/*` | Nur bei claudeos-core-Dateien (eingeschränkte Paths) | Bedingt |
 
-### Dateien, die über die standard-reference Regel gelesen werden
+### Dateien, die on-demand über Regel-Referenzen gelesen werden
 
-Die Regel `00.standard-reference.md` weist Claude Code an, die Standard-Dokumente vor dem Schreiben von Code zu Read:
+Jede Regel-Datei verlinkt im `## Reference`-Abschnitt auf den entsprechenden Standard. Claude liest nur den für die aktuelle Aufgabe relevanten Standard:
 
 - `claudeos-core/standard/**` — Coding-Patterns, ✅/❌ Beispiele, Namenskonventionen
 - `claudeos-core/database/**` — DB-Schema (für Queries, Mapper, Migrationen)
 
+`00.standard-reference.md` dient als Verzeichnis zum Entdecken von Standards ohne entsprechende Regel.
+
 ### Dateien, die NICHT gelesen werden (Kontexteinsparung)
 
 Explizit durch den `DO NOT Read`-Abschnitt der standard-reference Regel ausgeschlossen:
@@ -449,19 +485,31 @@ npx claudeos-core restore
 
 ## Was ist anders?
 
-| | ClaudeOS-Core | SuperClaude | Manuelle CLAUDE.md | Generische Skills |
-|---|---|---|---|---|
-| **Liest Ihren Code** | ✅ Tiefenanalyse (55–95 Kategorien) | ❌ Verhaltensinjektion | ❌ Manuelles Schreiben | ❌ Vorgefertigte Vorlagen |
-| **Projektspezifische Ausgabe** | ✅ Jede Datei spiegelt Ihre Muster wider | ❌ Generische Befehle | Teilweise | ❌ Einheitsgröße |
-| **Multi-Stack** | ✅ Auto-Erkennung + separate Analyse | ❌ Stack-agnostisch | Manuell | Variiert |
-| **Kotlin + CQRS/BFF** | ✅ Multi-Modul, Command/Query-Trennung | ❌ | ❌ | ❌ |
-| **Mehrsprachig** | ✅ 10 Sprachen, interaktiver Selektor | ❌ | ❌ | ❌ |
-| **Selbstverifizierung** | ✅ 5 Validierungstools | ❌ | ❌ | ❌ |
-| **Backup / Wiederherstellung** | ✅ Master Plan System | ❌ | ❌ | ❌ |
-| **Einrichtungszeit** | ~5–18 Min (automatisch) | ~5 Min (manuelle Konfig) | Stunden–Tage | ~5 Min |
+| | ClaudeOS-Core | Everything Claude Code (50K+ ⭐) | Harness | specs-generator | Claude `/init` |
+|---|---|---|---|---|---|
+| **Approach** | Code analyzes first, then LLM generates | Pre-built config presets | LLM designs agent teams | LLM generates spec docs | LLM writes CLAUDE.md |
+| **Reads your source code** | ✅ Deterministic static analysis | ❌ | ❌ | ❌ (LLM reads) | ❌ (LLM reads) |
+| **Stack detection** | Code confirms (ORM, DB, build tool, pkg manager) | N/A (stack-agnostic) | LLM guesses | LLM guesses | LLM guesses |
+| **Domain detection** | Code confirms (Java 5 patterns, Kotlin CQRS, Next.js FSD) | N/A | LLM guesses | N/A | N/A |
+| **Same project → Same result** | ✅ Deterministic analysis | ✅ (static files) | ❌ (LLM varies) | ❌ (LLM varies) | ❌ (LLM varies) |
+| **Large project handling** | Domain group splitting (4 domains / 40 files per group) | N/A | No splitting | No splitting | Context window limit |
+| **Output** | CLAUDE.md + Rules + Standards + Skills + Guides + Plans (40-50+ files) | Agents + Skills + Commands + Hooks | Agents + Skills | 6 spec documents | CLAUDE.md (1 file) |
+| **Output location** | `.claude/rules/` (auto-loaded by Claude Code) | `.claude/` various | `.claude/agents/` + `.claude/skills/` | `.claude/steering/` + `specs/` | `CLAUDE.md` |
+| **Post-generation verification** | ✅ 5 automated validators | ❌ | ❌ | ❌ | ❌ |
+| **Multi-language output** | ✅ 10 languages | ❌ | ❌ | ❌ | ❌ |
+| **Multi-stack** | ✅ Backend + Frontend simultaneous | ❌ Stack-agnostic | ❌ | ❌ | Partial |
+| **Agent orchestration** | ❌ | ✅ 28 agents | ✅ 6 patterns | ❌ | ❌ |
 
----
+### Key difference
 
+**Other tools give Claude "generally good instructions." ClaudeOS-Core gives Claude "instructions extracted from your actual code."**
+
+### Complementary, not competing
+
+ClaudeOS-Core: **project-specific rules**. Other tools: **agent orchestration**.
+Use both together.
+
+---
 ## FAQ
 
 **F: Ändert es meinen Quellcode?**

package/README.es.md

@@ -1,6 +1,6 @@
 # ClaudeOS-Core
 
-**Un solo comando. Toda la documentación de Claude Code — generada automáticamente desde tu código fuente.**
+**La única herramienta que lee tu código fuente primero, confirma tu stack y patrones con análisis determinístico, y genera reglas de Claude Code adaptadas exactamente a tu proyecto.**
 
 ```bash
 npx claudeos-core init
@@ -12,20 +12,50 @@ ClaudeOS-Core lee tu código fuente, extrae cada patrón que encuentra y genera
 
 ---
 
-## El Problema
+## ¿Por qué ClaudeOS-Core?
 
-Claude Code es potente, pero no conoce las convenciones de _tu_ proyecto. Escribir manualmente un `CLAUDE.md`, docenas de reglas y skills de scaffolding lleva horas — y se vuelven obsoletos en cuanto tu código evoluciona.
+> Humano describe el proyecto → LLM genera documentación
 
-## La Solución
+ClaudeOS-Core:
 
-ClaudeOS-Core automatiza todo el proceso:
+> Código analiza tu fuente → Código construye prompt personalizado → LLM genera documentación → Código verifica la salida
 
-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–19 archivos), Rules, Skills, Guides (9 archivos), Master Plans, documentación de BD y guía MCP
-4. **Valida** todo — 5 herramientas de verificación integradas garantizan la consistencia
+### El problema central: Los LLMs adivinan. El código confirma.
 
-Tiempo total: **5–18 minutos**, según el tamaño del proyecto. Cero configuración manual.
+Cuando le pides a Claude "analiza este proyecto", **adivina** tu stack, ORM y estructura de dominios.
+
+**ClaudeOS-Core no adivina.** Claude Node.js:
+
+- `build.gradle` / `package.json` / `pyproject.toml` → **confirmed**
+- directory scan → **confirmed**
+- Java 5 patterns, Kotlin CQRS/BFF, Next.js App Router/FSD → **classified**
+- domain groups → **split**
+- stack-specific prompt → **assembled**
+
+### El resultado
+
+Otras herramientas producen documentación "generalmente buena".
+ClaudeOS-Core produce documentación que sabe que tu proyecto usa `ApiResponse.ok()` (no `ResponseEntity.success()`), que tus mappers MyBatis XML están en `src/main/resources/mapper/{domain}/` — porque leyó tu código real.
+
+### Before & After
+
+**Sin ClaudeOS-Core**:
+```
+❌ JPA repository (MyBatis)
+❌ ResponseEntity.success() (ApiResponse.ok())
+❌ order/controller/ (controller/order/)
+→ 20 min fix per file
+```
+
+**Con ClaudeOS-Core**:
+```
+✅ MyBatis mapper + XML (build.gradle)
+✅ ApiResponse.ok() (source code)
+✅ controller/order/ (Pattern A)
+→ immediate match
+```
+
+Esta diferencia se acumula. 10 tareas/día × 20 minutos ahorrados = **más de 3 horas/día**.
 
 ---
 
@@ -79,6 +109,7 @@ Tipos de módulo soportados: `command`, `query`, `bff`, `integration`, `standalo
 - **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)
+- **Fallback de directorios profundos**: Para proyectos React/CRA/Vite/Vue/RN, escanea `**/components/*/`, `**/views/*/`, `**/screens/*/`, `**/containers/*/`, `**/pages/*/`, `**/routes/*/`, `**/modules/*/`, `**/domains/*/` a cualquier profundidad
 
 ---
 
@@ -117,7 +148,7 @@ bash claudeos-core-tools/bootstrap.sh
 
 ### Idioma de salida (10 idiomas)
 
-Al ejecutar `init` sin `--lang`, aparece un selector interactivo con teclas de flecha:
+Al ejecutar `init` sin `--lang`, aparece un selector interactivo con teclas de flecha o teclas numéricas:
 
 ```
 ╔══════════════════════════════════════════════════╗
@@ -132,7 +163,7 @@ Al ejecutar `init` sin `--lang`, aparece un selector interactivo con teclas de f
   ❯  5. es     — Español (Spanish)
      ...
 
-  ↑↓ Move  ↵ Select
+  ↑↓ Move  1-0 Jump  Enter Select  ESC Cancel
 ```
 
 La descripción cambia al idioma seleccionado al navegar. Para saltar el selector:
@@ -387,16 +418,21 @@ Así es como Claude Code lee la documentación generada por ClaudeOS-Core:
 | Archivo | Cuándo | Garantizado |
 |---|---|---|
 | `CLAUDE.md` | Al inicio de cada conversación | Siempre |
-| `.claude/rules/*.md` | Al editar archivos (vía `paths: ["**/*"]`) | Siempre |
-| `.claude/rules/00.core/00.standard-reference.md` | ↑ Incluido arriba | Siempre |
+| `.claude/rules/00.core/*` | Al editar archivos (`paths: ["**/*"]`) | Siempre |
+| `.claude/rules/10.backend/*` | Al editar archivos (`paths: ["**/*"]`) | Siempre |
+| `.claude/rules/30.security-db/*` | Al editar archivos (`paths: ["**/*"]`) | Siempre |
+| `.claude/rules/40.infra/*` | Solo al editar archivos config/infra (paths con alcance) | Condicional |
+| `.claude/rules/50.sync/*` | Solo al editar archivos claudeos-core (paths con alcance) | Condicional |
 
-### Archivos leídos vía regla standard-reference
+### Archivos leídos bajo demanda vía referencias en reglas
 
-La regla `00.standard-reference.md` instruye a Claude Code a Read los documentos estándar antes de escribir código:
+Cada archivo de regla enlaza a su standard correspondiente en la sección `## Reference`. Claude solo lee el standard relevante para la tarea actual:
 
 - `claudeos-core/standard/**` — Patrones de código, ejemplos ✅/❌, convenciones de nombres
 - `claudeos-core/database/**` — Schema DB (para queries, mappers, migraciones)
 
+`00.standard-reference.md` sirve como directorio para descubrir standards sin regla correspondiente.
+
 ### Archivos que NO se leen (ahorro de contexto)
 
 Excluidos explícitamente por la sección `DO NOT Read` de la regla standard-reference:
@@ -450,19 +486,31 @@ npx claudeos-core restore
 
 ## ¿En Qué se Diferencia?
 
-| | ClaudeOS-Core | SuperClaude | CLAUDE.md Manual | Skills Genéricos |
-|---|---|---|---|---|
-| **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 | ❌ | ❌ | ❌ |
-| **Multi-idioma** | ✅ 10 idiomas, selector interactivo | ❌ | ❌ | ❌ |
-| **Auto-verificación** | ✅ 5 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 |
+| | ClaudeOS-Core | Everything Claude Code (50K+ ⭐) | Harness | specs-generator | Claude `/init` |
+|---|---|---|---|---|---|
+| **Approach** | Code analyzes first, then LLM generates | Pre-built config presets | LLM designs agent teams | LLM generates spec docs | LLM writes CLAUDE.md |
+| **Reads your source code** | ✅ Deterministic static analysis | ❌ | ❌ | ❌ (LLM reads) | ❌ (LLM reads) |
+| **Stack detection** | Code confirms (ORM, DB, build tool, pkg manager) | N/A (stack-agnostic) | LLM guesses | LLM guesses | LLM guesses |
+| **Domain detection** | Code confirms (Java 5 patterns, Kotlin CQRS, Next.js FSD) | N/A | LLM guesses | N/A | N/A |
+| **Same project → Same result** | ✅ Deterministic analysis | ✅ (static files) | ❌ (LLM varies) | ❌ (LLM varies) | ❌ (LLM varies) |
+| **Large project handling** | Domain group splitting (4 domains / 40 files per group) | N/A | No splitting | No splitting | Context window limit |
+| **Output** | CLAUDE.md + Rules + Standards + Skills + Guides + Plans (40-50+ files) | Agents + Skills + Commands + Hooks | Agents + Skills | 6 spec documents | CLAUDE.md (1 file) |
+| **Output location** | `.claude/rules/` (auto-loaded by Claude Code) | `.claude/` various | `.claude/agents/` + `.claude/skills/` | `.claude/steering/` + `specs/` | `CLAUDE.md` |
+| **Post-generation verification** | ✅ 5 automated validators | ❌ | ❌ | ❌ | ❌ |
+| **Multi-language output** | ✅ 10 languages | ❌ | ❌ | ❌ | ❌ |
+| **Multi-stack** | ✅ Backend + Frontend simultaneous | ❌ Stack-agnostic | ❌ | ❌ | Partial |
+| **Agent orchestration** | ❌ | ✅ 28 agents | ✅ 6 patterns | ❌ | ❌ |
 
----
+### Key difference
 
+**Other tools give Claude "generally good instructions." ClaudeOS-Core gives Claude "instructions extracted from your actual code."**
+
+### Complementary, not competing
+
+ClaudeOS-Core: **project-specific rules**. Other tools: **agent orchestration**.
+Use both together.
+
+---
 ## FAQ
 
 **P: ¿Modifica mi código fuente?**

package/README.fr.md

@@ -1,6 +1,6 @@
 # ClaudeOS-Core
 
-**Une seule commande. Toute votre documentation Claude Code — générée automatiquement à partir de votre code source.**
+**Le seul outil qui lit d'abord votre code source, confirme votre stack et vos patterns par une analyse déterministe, puis génère des règles Claude Code adaptées exactement à votre projet.**
 
 ```bash
 npx claudeos-core init
@@ -12,20 +12,50 @@ ClaudeOS-Core lit votre codebase, extrait chaque pattern qu'il trouve et génèr
 
 ---
 
-## Le Problème
+## Pourquoi ClaudeOS-Core ?
 
-Claude Code est puissant, mais il ne connaît pas les conventions de _votre_ projet. Écrire manuellement un `CLAUDE.md`, des dizaines de règles et des skills de scaffolding prend des heures — et ils deviennent obsolètes dès que votre codebase évolue.
+> L'humain décrit le projet → Le LLM génère la documentation
 
-## La Solution
+ClaudeOS-Core:
 
-ClaudeOS-Core automatise l'ensemble du processus :
+> Le code analyse vos sources → Le code construit un prompt personnalisé → Le LLM génère la documentation → Le code vérifie la sortie
 
-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–19 fichiers), Rules, Skills, Guides (9 fichiers), Master Plans, documentation BD et guide MCP
-4. **Valide** tout — 5 outils de vérification intégrés garantissent la cohérence
+### Le problème fondamental : les LLMs devinent. Le code confirme.
 
-Temps total : **5–18 minutes**, selon la taille du projet. Zéro configuration manuelle.
+Quand vous demandez à Claude d'« analyser ce projet », il **devine** votre stack, ORM, structure de domaines.
+
+**ClaudeOS-Core ne devine pas.** Claude Node.js:
+
+- `build.gradle` / `package.json` / `pyproject.toml` → **confirmed**
+- directory scan → **confirmed**
+- Java 5 patterns, Kotlin CQRS/BFF, Next.js App Router/FSD → **classified**
+- domain groups → **split**
+- stack-specific prompt → **assembled**
+
+### Le résultat
+
+Les autres outils produisent une documentation « généralement bonne ».
+ClaudeOS-Core produit une documentation qui sait que votre projet utilise `ApiResponse.ok()` (pas `ResponseEntity.success()`), que vos mappers MyBatis XML sont dans `src/main/resources/mapper/{domain}/` — parce qu'il a lu votre vrai code.
+
+### Before & After
+
+**Sans ClaudeOS-Core**:
+```
+❌ JPA repository (MyBatis)
+❌ ResponseEntity.success() (ApiResponse.ok())
+❌ order/controller/ (controller/order/)
+→ 20 min fix per file
+```
+
+**Avec ClaudeOS-Core**:
+```
+✅ MyBatis mapper + XML (build.gradle)
+✅ ApiResponse.ok() (source code)
+✅ controller/order/ (Pattern A)
+→ immediate match
+```
+
+Cette différence s'accumule. 10 tâches/jour × 20 minutes économisées = **plus de 3 heures/jour**.
 
 ---
 
@@ -79,6 +109,7 @@ Types de modules supportés : `command`, `query`, `bff`, `integration`, `standal
 - **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)
+- **Fallback répertoires profonds** : Pour les projets React/CRA/Vite/Vue/RN, scanne `**/components/*/`, `**/views/*/`, `**/screens/*/`, `**/containers/*/`, `**/pages/*/`, `**/routes/*/`, `**/modules/*/`, `**/domains/*/` à toute profondeur
 
 ---
 
@@ -117,7 +148,7 @@ bash claudeos-core-tools/bootstrap.sh
 
 ### Langue de sortie (10 langues)
 
-En exécutant `init` sans `--lang`, un sélecteur interactif avec les touches fléchées apparaît :
+En exécutant `init` sans `--lang`, un sélecteur interactif apparaît (touches fléchées ou touches numériques) :
 
 ```
 ╔══════════════════════════════════════════════════╗
@@ -132,7 +163,7 @@ En exécutant `init` sans `--lang`, un sélecteur interactif avec les touches fl
   ❯  9. fr     — Français (French)
      ...
 
-  ↑↓ Move  ↵ Select
+  ↑↓ Move  1-0 Jump  Enter Select  ESC Cancel
 ```
 
 La description change dans la langue correspondante lors de la navigation. Pour passer le sélecteur :
@@ -387,16 +418,21 @@ Voici comment Claude Code lit effectivement la documentation générée par Clau
 | Fichier | Quand | Garanti |
 |---|---|---|
 | `CLAUDE.md` | Au début de chaque conversation | Toujours |
-| `.claude/rules/*.md` | Lors de l'édition de fichiers (via `paths: ["**/*"]`) | Toujours |
-| `.claude/rules/00.core/00.standard-reference.md` | ↑ Inclus ci-dessus | Toujours |
+| `.claude/rules/00.core/*` | Lors de l'édition de fichiers (`paths: ["**/*"]`) | Toujours |
+| `.claude/rules/10.backend/*` | Lors de l'édition de fichiers (`paths: ["**/*"]`) | Toujours |
+| `.claude/rules/30.security-db/*` | Lors de l'édition de fichiers (`paths: ["**/*"]`) | Toujours |
+| `.claude/rules/40.infra/*` | Uniquement pour les fichiers config/infra (paths scopés) | Conditionnel |
+| `.claude/rules/50.sync/*` | Uniquement pour les fichiers claudeos-core (paths scopés) | Conditionnel |
 
-### Fichiers lus via la règle standard-reference
+### Fichiers lus à la demande via les références des règles
 
-La règle `00.standard-reference.md` indique à Claude Code de Read les documents standards avant d'écrire du code :
+Chaque fichier de règle lie son standard correspondant dans la section `## Reference`. Claude ne lit que le standard pertinent pour la tâche en cours :
 
 - `claudeos-core/standard/**` — Patterns de code, exemples ✅/❌, conventions de nommage
 - `claudeos-core/database/**` — Schéma DB (pour requêtes, mappers, migrations)
 
+`00.standard-reference.md` sert de répertoire pour découvrir les standards sans règle correspondante.
+
 ### Fichiers NON lus (économie de contexte)
 
 Explicitement exclus par la section `DO NOT Read` de la règle standard-reference :
@@ -450,19 +486,31 @@ npx claudeos-core restore
 
 ## Quelle Différence ?
 
-| | ClaudeOS-Core | SuperClaude | CLAUDE.md Manuel | Skills Génériques |
-|---|---|---|---|---|
-| **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 | ❌ | ❌ | ❌ |
-| **Multilingue** | ✅ 10 langues, sélecteur interactif | ❌ | ❌ | ❌ |
-| **Auto-vérification** | ✅ 5 outils de validation | ❌ | ❌ | ❌ |
-| **Sauvegarde / Restauration** | ✅ Système Master Plan | ❌ | ❌ | ❌ |
-| **Temps de configuration** | ~5–18 min (automatique) | ~5 min (config manuelle) | Heures–Jours | ~5 min |
+| | ClaudeOS-Core | Everything Claude Code (50K+ ⭐) | Harness | specs-generator | Claude `/init` |
+|---|---|---|---|---|---|
+| **Approach** | Code analyzes first, then LLM generates | Pre-built config presets | LLM designs agent teams | LLM generates spec docs | LLM writes CLAUDE.md |
+| **Reads your source code** | ✅ Deterministic static analysis | ❌ | ❌ | ❌ (LLM reads) | ❌ (LLM reads) |
+| **Stack detection** | Code confirms (ORM, DB, build tool, pkg manager) | N/A (stack-agnostic) | LLM guesses | LLM guesses | LLM guesses |
+| **Domain detection** | Code confirms (Java 5 patterns, Kotlin CQRS, Next.js FSD) | N/A | LLM guesses | N/A | N/A |
+| **Same project → Same result** | ✅ Deterministic analysis | ✅ (static files) | ❌ (LLM varies) | ❌ (LLM varies) | ❌ (LLM varies) |
+| **Large project handling** | Domain group splitting (4 domains / 40 files per group) | N/A | No splitting | No splitting | Context window limit |
+| **Output** | CLAUDE.md + Rules + Standards + Skills + Guides + Plans (40-50+ files) | Agents + Skills + Commands + Hooks | Agents + Skills | 6 spec documents | CLAUDE.md (1 file) |
+| **Output location** | `.claude/rules/` (auto-loaded by Claude Code) | `.claude/` various | `.claude/agents/` + `.claude/skills/` | `.claude/steering/` + `specs/` | `CLAUDE.md` |
+| **Post-generation verification** | ✅ 5 automated validators | ❌ | ❌ | ❌ | ❌ |
+| **Multi-language output** | ✅ 10 languages | ❌ | ❌ | ❌ | ❌ |
+| **Multi-stack** | ✅ Backend + Frontend simultaneous | ❌ Stack-agnostic | ❌ | ❌ | Partial |
+| **Agent orchestration** | ❌ | ✅ 28 agents | ✅ 6 patterns | ❌ | ❌ |
 
----
+### Key difference
 
+**Other tools give Claude "generally good instructions." ClaudeOS-Core gives Claude "instructions extracted from your actual code."**
+
+### Complementary, not competing
+
+ClaudeOS-Core: **project-specific rules**. Other tools: **agent orchestration**.
+Use both together.
+
+---
 ## FAQ
 
 **Q : Est-ce que ça modifie mon code source ?**