claudeos-core 1.0.7 → 1.2.0

package/README.md

@@ -8,7 +8,7 @@ npx claudeos-core init
 
 ClaudeOS-Core reads your codebase, extracts every pattern it finds, and generates a complete set of Standards, Rules, Skills, and Guides tailored to _your_ project. After that, when you tell Claude Code "Create a CRUD for orders", it produces code that matches your existing patterns exactly.
 
-[🇨🇳 中文](./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) · [🇫🇷 Français](./README.fr.md) · [🇩🇪 Deutsch](./README.de.md) · [🇰🇷 한국어](./README.ko.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) · [🇫🇷 Français](./README.fr.md) · [🇩🇪 Deutsch](./README.de.md)
 
 ---
 
@@ -22,7 +22,7 @@ ClaudeOS-Core automates the entire process:
 
 1. **Scans** your project — detects stack, domains, ORM, DB, package manager automatically
 2. **Analyzes** your source code in depth — controller patterns, service layers, naming conventions, error handling, security, testing, and 50+ categories
-3. **Generates** a complete documentation ecosystem — `CLAUDE.md`, Standards (15–17 files), Rules, Skills, Guides (9 files), Master Plans, DB docs, and MCP guide
+3. **Generates** a complete documentation ecosystem — `CLAUDE.md`, Standards (15–19 files), Rules, Skills, Guides (9 files), Master Plans, DB docs, and MCP guide
 4. **Validates** everything — 6 built-in verification tools ensure consistency
 
 Total time: **5–18 minutes**, depending on project size. Zero manual configuration.
@@ -33,16 +33,51 @@ Total time: **5–18 minutes**, depending on project size. Zero manual configura
 
 | Stack | Detection | Analysis Depth |
 |---|---|---|
-| **Java / Spring Boot** | `build.gradle`, `pom.xml` | 10 categories, 59 sub-items |
+| **Java / Spring Boot** | `build.gradle`, `pom.xml`, 5 package patterns | 10 categories, 59 sub-items |
+| **Kotlin / Spring Boot** | `build.gradle.kts`, kotlin plugin, `settings.gradle.kts`, CQRS/BFF auto-detect | 12 categories, 95 sub-items |
 | **Node.js / Express / NestJS** | `package.json` | 9 categories, 57 sub-items |
-| **Next.js / React / Vue** | `package.json` (next, react, vue) | 9 categories, 55 sub-items |
+| **Next.js / React / Vue** | `package.json`, `next.config.*`, FSD support | 9 categories, 55 sub-items |
 | **Python / Django** | `requirements.txt`, `pyproject.toml` | 10 categories, 55 sub-items |
 | **Python / FastAPI** | `requirements.txt`, `pyproject.toml` | 10 categories, 58 sub-items |
 
-Auto-detected: language & version, framework & version, ORM (MyBatis, JPA, Prisma, TypeORM, SQLAlchemy, etc.), database (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), package manager (Gradle, Maven, npm, yarn, pnpm, pip, poetry).
+Auto-detected: language & version, framework & version, ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, etc.), database (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), package manager (Gradle, Maven, npm, yarn, pnpm, pip, poetry), architecture (CQRS, BFF — from module names), multi-module structure (from settings.gradle).
 
 **You don't specify anything. It's all detected automatically.**
 
+### Java Domain Detection (5 patterns with fallback)
+
+| Priority | Pattern | Structure | Example |
+|---|---|---|---|
+| A | Layer-first | `controller/{domain}/` | `controller/user/UserController.java` |
+| B | Domain-first | `{domain}/controller/` | `user/controller/UserController.java` |
+| D | Module prefix | `{module}/{domain}/controller/` | `front/member/controller/MemberController.java` |
+| E | DDD/Hexagonal | `{domain}/adapter/in/web/` | `user/adapter/in/web/UserController.java` |
+| C | Flat | `controller/*.java` | `controller/UserController.java` → extracts `user` from class name |
+
+Service-only domains (without controllers) are also detected. Skips: `common`, `config`, `util`, `front`, `admin`, `v1`, `v2`, etc.
+
+### Kotlin Multi-Module Domain Detection
+
+For Kotlin projects with Gradle multi-module structure (e.g., CQRS monorepo):
+
+| Step | What It Does | Example |
+|---|---|---|
+| 1 | Scan `settings.gradle.kts` for `include()` | Finds 14 modules |
+| 2 | Detect module type from name | `reservation-command-server` → type: `command` |
+| 3 | Extract domain from module name | `reservation-command-server` → domain: `reservation` |
+| 4 | Group same domain across modules | `reservation-command-server` + `common-query-server` → 1 domain |
+| 5 | Detect architecture | Has `command` + `query` modules → CQRS |
+
+Supported module types: `command`, `query`, `bff`, `integration`, `standalone`, `library`. Shared libraries (`shared-lib`, `integration-lib`) are detected as special domains.
+
+### Frontend Domain Detection
+
+- **App Router**: `app/{domain}/page.tsx` (Next.js)
+- **Pages Router**: `pages/{domain}/index.tsx`
+- **FSD (Feature-Sliced Design)**: `features/*/`, `widgets/*/`, `entities/*/`
+- **RSC/Client split**: Detects `client.tsx` pattern, tracks Server/Client component separation
+- **Config fallback**: Detects Next.js/Vite/Nuxt from config files when not in `package.json` (monorepo support)
+
 ---
 
 ## Quick Start
@@ -57,16 +92,153 @@ Auto-detected: language & version, framework & version, ORM (MyBatis, JPA, Prism
 ```bash
 cd /your/project/root
 
-# Option A: npx (recommended)
+# Option A: npx (recommended — no install needed)
 npx claudeos-core init
 
-# Option B: git clone (for development/contribution)
+# Option B: global install
+npm install -g claudeos-core
+claudeos-core init
+
+# Option C: project devDependency
+npm install --save-dev claudeos-core
+npx claudeos-core init
+
+# Option D: git clone (for development/contribution)
 git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
 bash claudeos-core-tools/bootstrap.sh
 ```
 
 That's it. After 5–18 minutes, all documentation is generated and ready to use.
 
+### Manual Step-by-Step Installation
+
+If you want full control over each phase — or if the automated pipeline fails at any step — you can run each stage manually. This is also useful for understanding how ClaudeOS-Core works internally.
+
+#### Step 1: Clone and install dependencies
+
+```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: Create directory structure
+
+```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: Run plan-installer (project analysis)
+
+This scans your project, detects the stack, finds domains, splits them into groups, and generates prompts.
+
+```bash
+node claudeos-core-tools/plan-installer/index.js
+```
+
+**Output (in `claudeos-core/generated/`):**
+- `project-analysis.json` — detected stack, domains, frontend info
+- `domain-groups.json` — domain groups for Pass 1
+- `pass1-backend-prompt.md` / `pass1-frontend-prompt.md` — analysis prompts
+- `pass2-prompt.md` — merge prompt
+- `pass3-prompt.md` — generation prompt
+
+You can inspect these files to verify detection accuracy before proceeding.
+
+#### Step 4: Pass 1 — Deep code analysis (per domain group)
+
+Run Pass 1 for each domain group. Check `domain-groups.json` for the number of groups.
+
+```bash
+# Check how many 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 each group (replace N with group number)
+# 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 group 2 (if exists):
+cat claudeos-core/generated/pass1-backend-prompt.md \
+  | sed "s/{{DOMAIN_GROUP}}/payment, system, delivery/g" \
+  | sed "s/{{PASS_NUM}}/2/g" \
+  | claude -p --dangerously-skip-permissions
+
+# For frontend groups, use pass1-frontend-prompt.md instead
+```
+
+**Verify:** `ls claudeos-core/generated/pass1-*.json` should show one JSON per group.
+
+#### Step 5: Pass 2 — Merge analysis results
+
+```bash
+cat claudeos-core/generated/pass2-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Verify:** `claudeos-core/generated/pass2-merged.json` should exist with 9+ top-level keys.
+
+#### Step 6: Pass 3 — Generate all documentation
+
+```bash
+cat claudeos-core/generated/pass3-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Verify:** `CLAUDE.md` should exist in your project root.
+
+#### Step 7: Run verification tools
+
+```bash
+# Generate metadata (required before other checks)
+node claudeos-core-tools/manifest-generator/index.js
+
+# Run all checks
+node claudeos-core-tools/health-checker/index.js
+
+# Or run individual checks:
+node claudeos-core-tools/import-linter/index.js        # @import path validation
+node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk consistency
+node claudeos-core-tools/sync-checker/index.js          # Unregistered/orphaned files
+node claudeos-core-tools/content-validator/index.js     # File quality checks
+node claudeos-core-tools/pass-json-validator/index.js   # Pass JSON format checks
+```
+
+#### Step 8: Verify the results
+
+```bash
+# Count generated files
+find .claude claudeos-core -type f | grep -v node_modules | wc -l
+
+# Check CLAUDE.md
+head -30 CLAUDE.md
+
+# Check a standard file
+cat claudeos-core/standard/00.core/01.project-overview.md | head -20
+
+# Check rules
+ls .claude/rules/*/
+```
+
+> **Tip:** If any step fails, you can fix the issue and re-run just that step. Pass 1/2 results are cached — if `pass1-N.json` or `pass2-merged.json` already exists, the automated pipeline skips them. Delete the file to force re-run.
+
 ### Start Using
 
 ```
@@ -108,7 +280,7 @@ npx claudeos-core init
 
 ### Why 3 Passes?
 
-**Pass 1** is the only pass that reads your source code. It selects representative files per domain and extracts patterns across 55–59 analysis categories (per stack). For large projects, Pass 1 runs multiple times — one per domain group. In multi-stack projects (e.g., Java backend + React frontend), backend and frontend domains use **different analysis prompts** tailored to each stack.
+**Pass 1** is the only pass that reads your source code. It selects representative files per domain and extracts patterns across 55–95 analysis categories (per stack). For large projects, Pass 1 runs multiple times — one per domain group. In multi-stack projects (e.g., Java backend + React frontend), backend and frontend domains use **different analysis prompts** tailored to each stack.
 
 **Pass 2** merges all Pass 1 results into a unified analysis: common patterns (100% shared), majority patterns (50%+ shared), domain-specific patterns, anti-patterns by severity, and cross-cutting concerns (naming, security, DB, testing, logging, performance). Backend and frontend results are merged together.
 
@@ -140,7 +312,7 @@ your-project/
 │   │   ├── pass1-frontend-prompt.md   ← Frontend analysis prompt (if detected)
 │   │   ├── pass2-prompt.md            ← Merge prompt
 │   │   └── pass3-prompt.md            ← Generation prompt (combined)
-│   ├── standard/                      ← Coding standards (15-17 files)
+│   ├── standard/                      ← Coding standards (15-19 files)
 │   │   ├── 00.core/                   ← Overview, architecture, naming
 │   │   ├── 10.backend-api/            ← API patterns (stack-specific)
 │   │   ├── 20.frontend-ui/            ← Frontend patterns (if detected)
@@ -247,9 +419,10 @@ npx claudeos-core restore
 
 | | ClaudeOS-Core | SuperClaude | Manual CLAUDE.md | Generic Skills |
 |---|---|---|---|---|
-| **Reads your code** | ✅ Deep analysis (55–59 categories) | ❌ Behavioral injection | ❌ Manual writing | ❌ Pre-built templates |
+| **Reads your code** | ✅ Deep analysis (55–95 categories) | ❌ Behavioral injection | ❌ Manual writing | ❌ Pre-built templates |
 | **Project-specific output** | ✅ Every file reflects your patterns | ❌ Generic commands | Partially | ❌ One-size-fits-all |
 | **Multi-stack** | ✅ Auto-detected + separate analysis | ❌ Stack-agnostic | Manual | Varies |
+| **Kotlin + CQRS/BFF** | ✅ Multi-module, Command/Query split | ❌ | ❌ | ❌ |
 | **Self-verifying** | ✅ 6 validation tools | ❌ | ❌ | ❌ |
 | **Backup / Restore** | ✅ Master Plan system | ❌ | ❌ | ❌ |
 | **Setup time** | ~5–18min (automated) | ~5min (manual config) | Hours–Days | ~5min |
@@ -273,6 +446,15 @@ Fully supported. ClaudeOS-Core auto-detects both stacks, tags domains as `backen
 **Q: What happens on re-run?**
 Pass 1/2 are skipped if their JSON already exists. Pass 3 always re-runs. Previous versions can be restored from Master Plans.
 
+**Q: Does it support Kotlin?**
+Yes. ClaudeOS-Core auto-detects Kotlin from `build.gradle.kts` or the kotlin plugin in `build.gradle`. It uses a dedicated `kotlin-spring` template with Kotlin-specific analysis (data classes, sealed classes, coroutines, extension functions, MockK, etc.).
+
+**Q: What about CQRS / BFF architecture?**
+Fully supported for Kotlin multi-module projects. ClaudeOS-Core reads `settings.gradle.kts`, detects module types (command, query, bff, integration) from module names, and groups the same domain across Command/Query modules. The generated standards include separate rules for command controllers vs query controllers, BFF/Feign patterns, and inter-module communication conventions.
+
+**Q: What about Gradle multi-module monorepos?**
+ClaudeOS-Core scans all submodules (`**/src/main/kotlin/**/*.kt`) regardless of nesting depth. Module types are inferred from naming conventions (e.g., `reservation-command-server` → domain: `reservation`, type: `command`). Shared libraries (`shared-lib`, `integration-lib`) are also detected.
+
 ---
 
 ## Template Structure
@@ -281,6 +463,7 @@ Pass 1/2 are skipped if their JSON already exists. Pass 3 always re-runs. Previo
 pass-prompts/templates/
 ├── common/                  # Shared header/footer
 ├── 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)
@@ -332,7 +515,13 @@ my-monorepo/                    ← Don't run here (root has no framework deps)
 
 **"npm install failed"** — Node.js version may be too low. Requires v18+.
 
-**"0 domains detected"** — Your project structure may be non-standard. See the detection patterns in the [Korean docs](./README.ko.md#-문제-해결--troubleshooting) for your stack.
+**"0 domains detected"** — Your project structure may be non-standard. See the detection patterns above for your stack.
+
+**"0 domains detected" on Kotlin project** — Ensure your project has `build.gradle.kts` (or `build.gradle` with kotlin plugin) at the root, and source files are under `**/src/main/kotlin/`. For multi-module projects, ensure `settings.gradle.kts` contains `include()` statements. Single-module Kotlin projects (without `settings.gradle`) are also supported — domains are extracted from package/class structure under `src/main/kotlin/`.
+
+**"Language detected as java instead of kotlin"** — ClaudeOS-Core checks the root `build.gradle(.kts)` first, then submodule build files. If the root build file uses `java` plugin without `kotlin`, but submodules use Kotlin, the tool checks up to 5 submodule build files as fallback. If still not detected, ensure at least one `build.gradle.kts` contains `kotlin("jvm")` or `org.jetbrains.kotlin`.
+
+**"CQRS not detected"** — Architecture detection relies on module names containing `command` and `query` keywords. If your modules use different naming (e.g., `write-server`, `read-server`), the CQRS architecture won't be auto-detected. You can manually adjust the generated prompts after plan-installer runs.
 
 ---
 

package/README.ru.md

@@ -8,7 +8,7 @@ npx claudeos-core init
 
 ClaudeOS-Core читает вашу кодовую базу, извлекает все паттерны и генерирует полный набор Standards, Rules, Skills и Guides, адаптированных под _ваш_ проект. После этого, когда вы говорите Claude Code «Создай CRUD для заказов», он генерирует код, точно соответствующий вашим существующим паттернам.
 
-[🇺🇸 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) · [🇫🇷 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) · [🇪🇸 Español](./README.es.md) · [🇻🇳 Tiếng Việt](./README.vi.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇫🇷 Français](./README.fr.md) · [🇩🇪 Deutsch](./README.de.md)
 
 ---
 
@@ -22,7 +22,7 @@ ClaudeOS-Core автоматизирует весь процесс:
 
 1. **Сканирует** ваш проект — автоматически определяет стек, домены, ORM, базу данных, пакетный менеджер
 2. **Глубоко анализирует** исходный код — паттерны контроллеров, сервисные слои, соглашения об именовании, обработка ошибок, безопасность, тестирование и 50+ категорий
-3. **Генерирует** полную экосистему документации — `CLAUDE.md`, Standards (15–17 файлов), Rules, Skills, Guides (9 файлов), Master Plans, документацию БД и руководство MCP
+3. **Генерирует** полную экосистему документации — `CLAUDE.md`, Standards (15–19 файлов), Rules, Skills, Guides (9 файлов), Master Plans, документацию БД и руководство MCP
 4. **Валидирует** всё — 6 встроенных инструментов проверки гарантируют консистентность
 
 Общее время: **5–18 минут**, в зависимости от размера проекта. Нулевая ручная настройка.
@@ -33,16 +33,53 @@ ClaudeOS-Core автоматизирует весь процесс:
 
 | Стек | Обнаружение | Глубина анализа |
 |---|---|---|
-| **Java / Spring Boot** | `build.gradle`, `pom.xml` | 10 категорий, 59 подпунктов |
+| **Java / Spring Boot** | `build.gradle`, `pom.xml`, 5 паттернов пакетов | 10 категорий, 59 подпунктов |
+| **Kotlin / Spring Boot** | `build.gradle.kts`, kotlin plugin, `settings.gradle.kts`, CQRS/BFF auto-detect | 12 категорий, 95 подпунктов |
 | **Node.js / Express / NestJS** | `package.json` | 9 категорий, 57 подпунктов |
-| **Next.js / React / Vue** | `package.json` (next, react, vue) | 9 категорий, 55 подпунктов |
+| **Next.js / React / Vue** | `package.json`, `next.config.*`, поддержка FSD | 9 категорий, 55 подпунктов |
 | **Python / Django** | `requirements.txt`, `pyproject.toml` | 10 категорий, 55 подпунктов |
 | **Python / FastAPI** | `requirements.txt`, `pyproject.toml` | 10 категорий, 58 подпунктов |
 
-Автоматическое определение: язык и версия, фреймворк и версия, ORM (MyBatis, JPA, Prisma, TypeORM, SQLAlchemy и др.), база данных (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), пакетный менеджер (Gradle, Maven, npm, yarn, pnpm, pip, poetry).
+Автоматическое определение: язык и версия, фреймворк и версия, ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy и др.), база данных (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), пакетный менеджер (Gradle, Maven, npm, yarn, pnpm, pip, poetry), архитектура (CQRS, BFF — определяется из имён модулей), мультимодульная структура (из settings.gradle).
 
 **Вам не нужно ничего указывать. Всё определяется автоматически.**
 
+
+### Обнаружение Java-доменов (5 паттернов с фолбэком)
+
+| Приоритет | Паттерн | Структура | Пример |
+|---|---|---|---|
+| A | Слой-первый | `controller/{domain}/` | `controller/user/UserController.java` |
+| B | Домен-первый | `{domain}/controller/` | `user/controller/UserController.java` |
+| D | Модуль-префикс | `{module}/{domain}/controller/` | `front/member/controller/MemberController.java` |
+| E | DDD/Гексагональный | `{domain}/adapter/in/web/` | `user/adapter/in/web/UserController.java` |
+| C | Плоский | `controller/*.java` | `controller/UserController.java` → извлекает `user` из имени класса |
+
+Домены только с сервисами (без контроллеров) тоже обнаруживаются. Пропускаются: `common`, `config`, `util`, `front`, `admin`, `v1`, `v2` и т.д.
+
+
+### Обнаружение доменов Kotlin мультимодульных проектов
+
+Для проектов Kotlin с Gradle мультимодульной структурой (например: CQRS монорепо):
+
+| Шаг | Действие | Пример |
+|---|---|---|
+| 1 | Сканирование `settings.gradle.kts` на наличие `include()` | Найдено 14 модулей |
+| 2 | Определение типа модуля по имени | `reservation-command-server` → тип: `command` |
+| 3 | Извлечение домена из имени модуля | `reservation-command-server` → домен: `reservation` |
+| 4 | Группировка одного домена по модулям | `reservation-command-server` + `common-query-server` → 1 домен |
+| 5 | Определение архитектуры | Есть модули `command` + `query` → CQRS |
+
+Поддерживаемые типы модулей: `command`, `query`, `bff`, `integration`, `standalone`, `library`. Общие библиотеки (`shared-lib`, `integration-lib`) обнаруживаются как специальные домены.
+
+### Обнаружение фронтенд-доменов
+
+- **App Router**: `app/{domain}/page.tsx` (Next.js)
+- **Pages Router**: `pages/{domain}/index.tsx`
+- **FSD (Feature-Sliced Design)**: `features/*/`, `widgets/*/`, `entities/*/`
+- **RSC/Client разделение**: Обнаружение паттерна `client.tsx`, отслеживание разделения Server/Client
+- **Фолбэк конфигурации**: Обнаружение Next.js/Vite/Nuxt из конфиг-файлов (поддержка monorepo)
+
 ---
 
 ## Быстрый старт
@@ -57,16 +94,138 @@ ClaudeOS-Core автоматизирует весь процесс:
 ```bash
 cd /your/project/root
 
-# Вариант A: npx (рекомендуется)
+# Вариант A: npx (рекомендуется — установка не нужна)
 npx claudeos-core init
 
-# Вариант B: git clone (для разработки/контрибуции)
+# Вариант B: глобальная установка
+npm install -g claudeos-core
+claudeos-core init
+
+# Вариант C: devDependency проекта
+npm install --save-dev claudeos-core
+npx claudeos-core init
+
+# Вариант D: git clone (для разработки/контрибуции)
 git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
 bash claudeos-core-tools/bootstrap.sh
 ```
 
 Это всё. Через 5–18 минут вся документация сгенерирована и готова к использованию.
 
+### Ручная пошаговая установка
+
+Если вы хотите полностью контролировать каждый этап — или если автоматический пайплайн сбоит на каком-то шаге — можно запустить каждый этап вручную. Это также полезно для понимания внутренней работы ClaudeOS-Core.
+
+#### Step 1: Клонирование и установка зависимостей
+
+```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: Создание структуры каталогов
+
+```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: Запуск plan-installer (анализ проекта)
+
+Сканирует ваш проект, определяет стек, находит домены, разделяет на группы и генерирует промпты.
+
+```bash
+node claudeos-core-tools/plan-installer/index.js
+```
+
+**Вывод (`claudeos-core/generated/`):**
+- `project-analysis.json` — обнаруженный стек, домены, информация о фронтенде
+- `domain-groups.json` — группы доменов для Pass 1
+- `pass1-backend-prompt.md` / `pass1-frontend-prompt.md` — промпты анализа
+- `pass2-prompt.md` — промпт объединения
+- `pass3-prompt.md` — промпт генерации
+
+Вы можете проверить эти файлы для верификации точности определения перед продолжением.
+
+#### Step 4: Pass 1 — Глубокий анализ кода по группам доменов
+
+Запустите Pass 1 для каждой группы доменов. Проверьте `domain-groups.json` для количества групп.
+
+```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
+```
+
+**Проверка:** `ls claudeos-core/generated/pass1-*.json` должен показать по одному JSON на группу.
+
+#### Step 5: Pass 2 — Объединение результатов анализа
+
+```bash
+cat claudeos-core/generated/pass2-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Проверка:** `claudeos-core/generated/pass2-merged.json` должен существовать с 9+ ключами верхнего уровня.
+
+#### Step 6: Pass 3 — Генерация всей документации
+
+```bash
+cat claudeos-core/generated/pass3-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Проверка:** `CLAUDE.md` должен существовать в корне проекта.
+
+#### Step 7: Запуск инструментов проверки
+
+```bash
+# Генерация метаданных (обязательно перед другими проверками)
+node claudeos-core-tools/manifest-generator/index.js
+
+# Запуск всех проверок
+node claudeos-core-tools/health-checker/index.js
+
+# Или запуск отдельных проверок:
+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: Проверка результатов
+
+```bash
+find .claude claudeos-core -type f | grep -v node_modules | wc -l
+head -30 CLAUDE.md
+ls .claude/rules/*/
+```
+
+> **Совет:** Если какой-то шаг не удался, можно перезапустить только этот шаг. Результаты Pass 1/2 кешируются — если `pass1-N.json` или `pass2-merged.json` уже существует, автоматический пайплайн их пропускает. Удалите файл для принудительного повтора.
+
 ### Начинайте использовать
 
 ```
@@ -108,7 +267,7 @@ npx claudeos-core init
 
 ### Почему 3 Pass?
 
-**Pass 1** — единственный pass, который читает исходный код. Он выбирает репрезентативные файлы по доменам и извлекает паттерны по 55–59 категориям анализа (по стеку). Для крупных проектов Pass 1 запускается несколько раз — по одному на группу доменов. В мульти-стек проектах (например: Java backend + React frontend) backend и frontend используют **разные промпты анализа**, адаптированные под каждый стек.
+**Pass 1** — единственный pass, который читает исходный код. Он выбирает репрезентативные файлы по доменам и извлекает паттерны по 55–95 категориям анализа (по стеку). Для крупных проектов Pass 1 запускается несколько раз — по одному на группу доменов. В мульти-стек проектах (например: Java backend + React frontend) backend и frontend используют **разные промпты анализа**, адаптированные под каждый стек.
 
 **Pass 2** объединяет все результаты Pass 1 в единый анализ: общие паттерны (100% совпадение), мажоритарные паттерны (50%+), доменно-специфичные паттерны, анти-паттерны по степени серьёзности и сквозные аспекты (именование, безопасность, БД, тестирование, логирование, производительность).
 
@@ -134,7 +293,7 @@ your-project/
 │
 ├── claudeos-core/                     ← Основная директория вывода
 │   ├── generated/                     ← JSON анализа + динамические промпты
-│   ├── standard/                      ← Стандарты кода (15-17 файлов)
+│   ├── standard/                      ← Стандарты кода (15-19 файлов)
 │   ├── skills/                        ← Skills скаффолдинга CRUD
 │   ├── guide/                         ← Онбординг, FAQ, устранение неполадок (9 файлов)
 │   ├── plan/                          ← Master Plans (бэкап/восстановление)
@@ -228,9 +387,10 @@ npx claudeos-core restore
 
 | | ClaudeOS-Core | SuperClaude | Ручной CLAUDE.md | Универсальные Skills |
 |---|---|---|---|---|
-| **Читает ваш код** | ✅ Глубокий анализ (55–59 категорий) | ❌ Инъекция поведения | ❌ Ручное написание | ❌ Готовые шаблоны |
+| **Читает ваш код** | ✅ Глубокий анализ (55–95 категорий) | ❌ Инъекция поведения | ❌ Ручное написание | ❌ Готовые шаблоны |
 | **Вывод под проект** | ✅ Каждый файл отражает ваши паттерны | ❌ Универсальные команды | Частично | ❌ Один размер для всех |
 | **Мульти-стек** | ✅ Автоопределение + раздельный анализ | ❌ Стек-агностик | Вручную | Неопределённо |
+| **Kotlin + CQRS/BFF** | ✅ Мультимодульный, разделение Command/Query | ❌ | ❌ | ❌ |
 | **Самопроверка** | ✅ 6 инструментов валидации | ❌ | ❌ | ❌ |
 | **Бэкап / Восстановление** | ✅ Система Master Plan | ❌ | ❌ | ❌ |
 | **Время настройки** | ~5–18 мин (автоматически) | ~5 мин (ручная настройка) | Часы–Дни | ~5 мин |
@@ -254,6 +414,15 @@ npx claudeos-core restore
 **В: Что происходит при повторном запуске?**
 Pass 1/2 пропускаются, если их JSON уже существует. Pass 3 всегда перезапускается. Предыдущие версии можно восстановить из Master Plans.
 
+**В: Поддерживается ли Kotlin?**
+Да. ClaudeOS-Core автоматически определяет Kotlin из `build.gradle.kts` или плагина kotlin в `build.gradle`. Используется специальный шаблон `kotlin-spring` с Kotlin-специфичным анализом (data class, sealed class, корутины, функции-расширения, MockK и т.д.).
+
+**В: Как насчёт архитектуры CQRS / BFF?**
+Полностью поддерживается для Kotlin мультимодульных проектов. ClaudeOS-Core читает `settings.gradle.kts`, определяет типы модулей (command, query, bff, integration) из их имён и группирует одинаковые домены по модулям Command/Query. Сгенерированные стандарты включают отдельные правила для command-контроллеров и query-контроллеров, паттерны BFF/Feign и соглашения о межмодульном взаимодействии.
+
+**В: Как насчёт Gradle мультимодульных monorepo?**
+ClaudeOS-Core сканирует все подмодули (`**/src/main/kotlin/**/*.kt`) независимо от глубины вложенности. Типы модулей определяются из соглашений об именовании (например, `reservation-command-server` → домен: `reservation`, тип: `command`). Общие библиотеки (`shared-lib`, `integration-lib`) также обнаруживаются.
+
 ---
 
 ## Структура шаблонов
@@ -262,6 +431,7 @@ Pass 1/2 пропускаются, если их JSON уже существуе
 pass-prompts/templates/
 ├── common/                  # Общий заголовок/футер
 ├── 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/                    ← Не запускайте здесь (в к
 
 **"npm install failed"** — Версия Node.js может быть слишком старой. Требуется v18+.
 
-**"0 domains detected"** — Структура вашего проекта может быть нестандартной. Смотрите паттерны обнаружения в [корейской документации](./README.ko.md#-문제-해결--troubleshooting) для вашего стека.
+**"0 domains detected"** — Структура вашего проекта может быть нестандартной. Смотрите паттерны обнаружения в [корейской документации](./README.ko.md#트러블슈팅) для вашего стека.
+
+**«0 доменов обнаружено» в Kotlin-проекте** — Убедитесь, что в корне проекта есть `build.gradle.kts` (или `build.gradle` с плагином kotlin), а исходные файлы находятся в `**/src/main/kotlin/`. Для мультимодульных проектов `settings.gradle.kts` должен содержать операторы `include()`. Одномодульные Kotlin-проекты (без `settings.gradle`) также поддерживаются — домены извлекаются из структуры пакетов/классов в `src/main/kotlin/`.
+
+**«Язык определён как java вместо kotlin»** — ClaudeOS-Core сначала проверяет корневой `build.gradle(.kts)`, затем файлы сборки подмодулей. Убедитесь, что хотя бы один содержит `kotlin("jvm")` или `org.jetbrains.kotlin`.
+
+**«CQRS не обнаружен»** — Определение архитектуры зависит от наличия ключевых слов `command` и `query` в именах модулей. Если ваши модули используют другие имена, можно вручную скорректировать сгенерированные промпты.
 
 ---