claudeos-core 1.0.7 → 1.2.0

package/README.vi.md

@@ -8,7 +8,7 @@ npx claudeos-core init
 
 ClaudeOS-Core đọc codebase của bạn, trích xuất mọi pattern tìm thấy và tạo ra bộ Standards, Rules, Skills và Guides hoàn chỉnh được tùy chỉnh cho _dự án của bạn_. Sau đó, khi bạn nói với Claude Code "Tạo CRUD cho đơn hàng", nó sẽ tạo ra code khớp chính xác với các pattern hiện có của bạn.
 
-[🇺🇸 English](./README.md) · [🇨🇳 中文](./README.zh-CN.md) · [🇯🇵 日本語](./README.ja.md) · [🇪🇸 Español](./README.es.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) · [🇪🇸 Español](./README.es.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇷🇺 Русский](./README.ru.md) · [🇫🇷 Français](./README.fr.md) · [🇩🇪 Deutsch](./README.de.md)
 
 ---
 
@@ -22,7 +22,7 @@ ClaudeOS-Core tự động hóa toàn bộ quy trình:
 
 1. **Quét** dự án — tự động phát hiện stack, domain, ORM, database, package manager
 2. **Phân tích chuyên sâu** mã nguồn — controller patterns, service layers, quy ước đặt tên, xử lý lỗi, bảo mật, testing và hơn 50 danh mục
-3. **Tạo** hệ sinh thái tài liệu hoàn chỉnh — `CLAUDE.md`, Standards (15–17 file), Rules, Skills, Guides (9 file), Master Plans, tài liệu DB và hướng dẫn MCP
+3. **Tạo** hệ sinh thái tài liệu hoàn chỉnh — `CLAUDE.md`, Standards (15–19 file), Rules, Skills, Guides (9 file), Master Plans, tài liệu DB và hướng dẫn MCP
 4. **Xác thực** mọi thứ — 6 công cụ kiểm tra tích hợp đảm bảo tính nhất quán
 
 Tổng thời gian: **5–18 phút**, tùy thuộc vào quy mô dự án. Không cần cấu hình thủ công.
@@ -33,16 +33,53 @@ Tổng thời gian: **5–18 phút**, tùy thuộc vào quy mô dự án. Không
 
 | Stack | Phát Hiện | Độ Sâu Phân Tích |
 |---|---|---|
-| **Java / Spring Boot** | `build.gradle`, `pom.xml` | 10 danh mục, 59 mục con |
+| **Java / Spring Boot** | `build.gradle`, `pom.xml`, 5 package patterns | 10 danh mục, 59 mục con |
+| **Kotlin / Spring Boot** | `build.gradle.kts`, kotlin plugin, `settings.gradle.kts`, CQRS/BFF auto-detect | 12 danh mục, 95 mục con |
 | **Node.js / Express / NestJS** | `package.json` | 9 danh mục, 57 mục con |
-| **Next.js / React / Vue** | `package.json` (next, react, vue) | 9 danh mục, 55 mục con |
+| **Next.js / React / Vue** | `package.json`, `next.config.*`, hỗ trợ FSD | 9 danh mục, 55 mục con |
 | **Python / Django** | `requirements.txt`, `pyproject.toml` | 10 danh mục, 55 mục con |
 | **Python / FastAPI** | `requirements.txt`, `pyproject.toml` | 10 danh mục, 58 mục con |
 
-Tự động phát hiện: ngôn ngữ & phiên bản, framework & phiên bản, ORM (MyBatis, JPA, Prisma, TypeORM, SQLAlchemy, v.v.), database (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), package manager (Gradle, Maven, npm, yarn, pnpm, pip, poetry).
+Tự động phát hiện: ngôn ngữ & phiên bản, framework & phiên bản, ORM (MyBatis, JPA, Exposed, Prisma, TypeORM, SQLAlchemy, v.v.), database (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), package manager (Gradle, Maven, npm, yarn, pnpm, pip, poetry), kiến trúc (CQRS, BFF — phát hiện từ tên module), cấu trúc multi-module (từ settings.gradle).
 
 **Bạn không cần chỉ định gì cả. Tất cả được phát hiện tự động.**
 
+
+### Phát Hiện Domain Java (5 pattern với fallback)
+
+| Ưu tiên | Pattern | Cấu trúc | Ví dụ |
+|---|---|---|---|
+| A | Layer trước | `controller/{domain}/` | `controller/user/UserController.java` |
+| B | Domain trước | `{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 | Phẳng | `controller/*.java` | `controller/UserController.java` → trích `user` từ tên class |
+
+Các domain chỉ có service (không có controller) cũng được phát hiện. Bỏ qua: `common`, `config`, `util`, `front`, `admin`, `v1`, `v2`, v.v.
+
+
+### Phát Hiện Domain Kotlin Multi-Module
+
+Dành cho dự án Kotlin với cấu trúc Gradle multi-module (ví dụ: CQRS monorepo):
+
+| Bước | Hành Động | Ví Dụ |
+|---|---|---|
+| 1 | Quét `settings.gradle.kts` tìm `include()` | Tìm thấy 14 module |
+| 2 | Phát hiện loại module từ tên | `reservation-command-server` → type: `command` |
+| 3 | Trích xuất domain từ tên module | `reservation-command-server` → domain: `reservation` |
+| 4 | Nhóm cùng domain qua các module | `reservation-command-server` + `common-query-server` → 1 domain |
+| 5 | Phát hiện kiến trúc | Có module `command` + `query` → CQRS |
+
+Loại module hỗ trợ: `command`, `query`, `bff`, `integration`, `standalone`, `library`. Thư viện chia sẻ (`shared-lib`, `integration-lib`) được phát hiện như domain đặc biệt.
+
+### Phát Hiện Domain 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**: Phát hiện pattern `client.tsx`, theo dõi tách Server/Client
+- **Config fallback**: Phát hiện Next.js/Vite/Nuxt từ file config (hỗ trợ monorepo)
+
 ---
 
 ## Bắt Đầu Nhanh
@@ -57,15 +94,137 @@ Tự động phát hiện: ngôn ngữ & phiên bản, framework & phiên bản,
 ```bash
 cd /your/project/root
 
-# Cách A: npx (khuyến nghị)
+# Cách A: npx (khuyến nghị — không cần cài đặt)
 npx claudeos-core init
 
-# Cách B: git clone (cho phát triển/đóng góp)
+# Cách B: cài đặt global
+npm install -g claudeos-core
+claudeos-core init
+
+# Cách C: devDependency của dự án
+npm install --save-dev claudeos-core
+npx claudeos-core init
+
+# Cách D: git clone (cho phát triển/đóng góp)
 git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
 bash claudeos-core-tools/bootstrap.sh
 ```
 
-Vậy là xong. Sau 5–18 phút, toàn bộ tài liệu được tạo và sẵn sàng sử dụng.
+Chỉ vậy thôi. Sau 5–18 phút, tất cả tài liệu được tạo và sẵn sàng sử dụng.
+
+### Cài Đặt Thủ Công Từng Bước
+
+Nếu bạn muốn kiểm soát hoàn toàn từng giai đoạn — hoặc nếu pipeline tự động thất bại ở bước nào đó — bạn có thể chạy từng bước thủ công. Điều này cũng hữu ích để hiểu cách ClaudeOS-Core hoạt động bên trong.
+
+#### Step 1: Clone và cài đặt 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: Tạo cấu trúc thư mục
+
+```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: Chạy plan-installer (phân tích dự án)
+
+Quét dự án, phát hiện stack, tìm domain, chia nhóm và tạo prompt.
+
+```bash
+node claudeos-core-tools/plan-installer/index.js
+```
+
+**Đầu ra (`claudeos-core/generated/`):**
+- `project-analysis.json` — stack phát hiện, domain, thông tin frontend
+- `domain-groups.json` — nhóm domain cho Pass 1
+- `pass1-backend-prompt.md` / `pass1-frontend-prompt.md` — prompt phân tích
+- `pass2-prompt.md` — prompt hợp nhất
+- `pass3-prompt.md` — prompt tạo
+
+Bạn có thể kiểm tra các file này để xác minh độ chính xác phát hiện trước khi tiếp tục.
+
+#### Step 4: Pass 1 — Phân tích code sâu theo nhóm domain
+
+Chạy Pass 1 cho mỗi nhóm domain. Kiểm tra `domain-groups.json` để biết số nhóm.
+
+```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
+```
+
+**Xác minh:** `ls claudeos-core/generated/pass1-*.json` phải hiển thị một JSON cho mỗi nhóm.
+
+#### Step 5: Pass 2 — Hợp nhất kết quả phân tích
+
+```bash
+cat claudeos-core/generated/pass2-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Xác minh:** `claudeos-core/generated/pass2-merged.json` phải tồn tại với 9+ key cấp cao nhất.
+
+#### Step 6: Pass 3 — Tạo tất cả tài liệu
+
+```bash
+cat claudeos-core/generated/pass3-prompt.md \
+  | claude -p --dangerously-skip-permissions
+```
+
+**Xác minh:** `CLAUDE.md` phải tồn tại ở thư mục gốc dự án.
+
+#### Step 7: Chạy công cụ xác thực
+
+```bash
+# Tạo metadata (bắt buộc trước các kiểm tra khác)
+node claudeos-core-tools/manifest-generator/index.js
+
+# Chạy tất cả kiểm tra
+node claudeos-core-tools/health-checker/index.js
+
+# Hoặc chạy kiểm tra riêng lẻ:
+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: Xác minh kết quả
+
+```bash
+find .claude claudeos-core -type f | grep -v node_modules | wc -l
+head -30 CLAUDE.md
+ls .claude/rules/*/
+```
+
+> **Mẹo:** Nếu bước nào thất bại, bạn có thể chạy lại chỉ bước đó. Kết quả Pass 1/2 được cache — nếu `pass1-N.json` hoặc `pass2-merged.json` đã tồn tại, pipeline tự động sẽ bỏ qua. Xóa file để buộc chạy lại.
 
 ### Bắt Đầu Sử Dụng
 
@@ -108,7 +267,7 @@ npx claudeos-core init
 
 ### Tại Sao 3 Pass?
 
-**Pass 1** là pass duy nhất đọc mã nguồn. Nó chọn file đại diện cho mỗi domain và trích xuất pattern trên 55–59 danh mục phân tích (theo stack). Với dự án lớn, Pass 1 chạy nhiều lần — mỗi nhóm domain một lần. Trong dự án multi-stack (ví dụ: Java backend + React frontend), backend và frontend sử dụng **prompt phân tích riêng biệt** phù hợp với từng stack.
+**Pass 1** là pass duy nhất đọc mã nguồn. Nó chọn file đại diện cho mỗi domain và trích xuất pattern trên 55–95 danh mục phân tích (theo stack). Với dự án lớn, Pass 1 chạy nhiều lần — mỗi nhóm domain một lần. Trong dự án multi-stack (ví dụ: Java backend + React frontend), backend và frontend sử dụng **prompt phân tích riêng biệt** phù hợp với từng stack.
 
 **Pass 2** hợp nhất tất cả kết quả Pass 1 thành phân tích thống nhất: pattern chung (100% chia sẻ), pattern đa số (50%+ chia sẻ), pattern riêng domain, anti-pattern theo mức độ nghiêm trọng và các mối quan tâm xuyên suốt (đặt tên, bảo mật, DB, testing, logging, hiệu suất).
 
@@ -134,7 +293,7 @@ your-project/
 │
 ├── claudeos-core/                     ← Thư mục đầu ra chính
 │   ├── generated/                     ← JSON phân tích + prompt động
-│   ├── standard/                      ← Tiêu chuẩn code (15-17 file)
+│   ├── standard/                      ← Tiêu chuẩn code (15-19 file)
 │   ├── skills/                        ← Skills scaffolding CRUD
 │   ├── guide/                         ← Onboarding, FAQ, troubleshooting (9 file)
 │   ├── plan/                          ← Master Plans (backup/khôi phục)
@@ -228,9 +387,10 @@ npx claudeos-core restore
 
 | | ClaudeOS-Core | SuperClaude | CLAUDE.md Thủ Công | Skills Chung |
 |---|---|---|---|---|
-| **Đọc code của bạn** | ✅ Phân tích sâu (55–59 danh mục) | ❌ Tiêm hành vi | ❌ Viết thủ công | ❌ Template có sẵn |
+| **Đọc code của bạn** | ✅ Phân tích sâu (55–95 danh mục) | ❌ Tiêm hành vi | ❌ Viết thủ công | ❌ Template có sẵn |
 | **Đầu ra riêng dự án** | ✅ Mọi file phản ánh pattern của bạn | ❌ Lệnh chung | Một phần | ❌ Một cỡ cho tất cả |
 | **Multi-stack** | ✅ Tự phát hiện + phân tích riêng | ❌ Không phân biệt stack | Thủ công | Không chắc |
+| **Kotlin + CQRS/BFF** | ✅ Multi-module, Command/Query split | ❌ | ❌ | ❌ |
 | **Tự xác thực** | ✅ 6 công cụ validation | ❌ | ❌ | ❌ |
 | **Backup / Khôi phục** | ✅ Hệ thống Master Plan | ❌ | ❌ | ❌ |
 | **Thời gian cài đặt** | ~5–18 phút (tự động) | ~5 phút (cấu hình thủ công) | Hàng giờ–ngày | ~5 phút |
@@ -254,6 +414,15 @@ Hỗ trợ hoàn toàn. ClaudeOS-Core tự phát hiện cả hai stack, gắn ta
 **H: Chạy lại thì sao?**
 Pass 1/2 bị bỏ qua nếu JSON đã tồn tại. Pass 3 luôn chạy lại. Phiên bản trước có thể khôi phục từ Master Plans.
 
+**H: Có hỗ trợ Kotlin không?**
+Có. ClaudeOS-Core tự động phát hiện Kotlin từ `build.gradle.kts` hoặc kotlin plugin trong `build.gradle`. Sử dụng template chuyên dụng `kotlin-spring` để phân tích các pattern đặc thù của Kotlin (data class, sealed class, coroutine, extension function, MockK, v.v.).
+
+**H: Kiến trúc CQRS / BFF thì sao?**
+Hỗ trợ đầy đủ cho các dự án Kotlin multi-module. ClaudeOS-Core đọc `settings.gradle.kts`, phát hiện loại module (command, query, bff, integration) từ tên module, và nhóm các module Command/Query cùng domain lại. Các standard được tạo bao gồm quy tắc riêng cho command controller vs query controller, pattern BFF/Feign và quy ước giao tiếp giữa các module.
+
+**H: Gradle multi-module monorepo thì sao?**
+ClaudeOS-Core quét tất cả submodule (`**/src/main/kotlin/**/*.kt`) bất kể độ sâu lồng nhau. Loại module được suy luận từ quy ước đặt tên (ví dụ: `reservation-command-server` → domain: `reservation`, type: `command`). Thư viện chia sẻ (`shared-lib`, `integration-lib`) cũng được phát hiện.
+
 ---
 
 ## Cấu Trúc Template
@@ -262,6 +431,7 @@ Pass 1/2 bị bỏ qua nếu JSON đã tồn tại. Pass 3 luôn chạy lại. P
 pass-prompts/templates/
 ├── common/                  # Header/footer chung
 ├── 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/                    ← Đừng chạy ở đây (gốc không có f
 
 **"npm install failed"** — Phiên bản Node.js có thể quá thấp. Yêu cầu v18+.
 
-**"0 domains detected"** — Cấu trúc dự án có thể không chuẩn. Xem pattern phát hiện trong [tài liệu tiếng Hàn](./README.ko.md#-문제-해결--troubleshooting) cho stack của bạn.
+**"0 domains detected"** — Cấu trúc dự án có thể không chuẩn. Xem pattern phát hiện trong [tài liệu tiếng Hàn](./README.ko.md#트러블슈팅) cho stack của bạn.
+
+**Dự án Kotlin "phát hiện 0 domain"** — Đảm bảo thư mục gốc có `build.gradle.kts` (hoặc `build.gradle` với kotlin plugin), và file nguồn nằm dưới `**/src/main/kotlin/`. Với dự án multi-module, `settings.gradle.kts` phải chứa câu lệnh `include()`. Dự án Kotlin đơn module (không có `settings.gradle`) cũng được hỗ trợ — domain được trích xuất từ cấu trúc package/class dưới `src/main/kotlin/`.
+
+**"Ngôn ngữ phát hiện là java thay vì kotlin"** — ClaudeOS-Core kiểm tra `build.gradle(.kts)` gốc trước, sau đó kiểm tra file build của submodule. Đảm bảo ít nhất một file chứa `kotlin("jvm")` hoặc `org.jetbrains.kotlin`.
+
+**"Không phát hiện CQRS"** — Phát hiện kiến trúc phụ thuộc vào tên module chứa từ khóa `command` và `query`. Nếu module của bạn dùng tên khác, có thể điều chỉnh thủ công các prompt đã tạo.
 
 ---
 

package/README.zh-CN.md

@@ -8,7 +8,7 @@ npx claudeos-core init
 
 ClaudeOS-Core 读取你的代码库，提取所有模式，生成一套完全适配 _你的_ 项目的 Standards、Rules、Skills 和 Guides。之后，当你告诉 Claude Code "创建一个订单 CRUD"时，它会生成完全符合你现有模式的代码。
 
-[🇺🇸 English](./README.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)
+[🇺🇸 English](./README.md) · [🇰🇷 한국어](./README.ko.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 将整个过程自动化：
 
 1. **扫描** 你的项目——自动检测技术栈、领域、ORM、数据库、包管理器
 2. **深度分析** 源代码——控制器模式、服务层、命名规范、异常处理、安全、测试等 50+ 个类别
-3. **生成** 完整的文档体系——`CLAUDE.md`、Standards（15–17 个文件）、Rules、Skills、Guides（9 个文件）、Master Plans、DB 文档和 MCP 指南
+3. **生成** 完整的文档体系——`CLAUDE.md`、Standards（15–19 个文件）、Rules、Skills、Guides（9 个文件）、Master Plans、DB 文档和 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 插件、`settings.gradle.kts`、CQRS/BFF 自动检测 | 12 大类，95 小项 |
 | **Node.js / Express / NestJS** | `package.json` | 9 大类，57 小项 |
 | **Next.js / React / Vue** | `package.json`（next、react、vue） | 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` |
+
+无 Controller 的纯 Service 域也会被检测。跳过：`common`、`config`、`util`、`front`、`admin`、`v1`、`v2` 等。
+
+
+### Kotlin 多模块域检测
+
+适用于 Gradle 多模块结构的 Kotlin 项目（如 CQRS 单体仓库）：
+
+| 步骤 | 操作 | 示例 |
+|---|---|---|
+| 1 | 扫描 `settings.gradle.kts` 中的 `include()` | 发现 14 个模块 |
+| 2 | 从模块名检测类型 | `reservation-command-server` → type: `command` |
+| 3 | 从模块名提取域 | `reservation-command-server` → domain: `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（功能切片设计）**：`features/*/`、`widgets/*/`、`entities/*/`
+- **RSC/Client 分离**：检测 `client.tsx` 模式，追踪服务端/客户端组件分离
+- **配置文件回退**：从配置文件检测 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** 是唯一读取源代码的阶段。它为每个领域选择代表性文件，跨 55–59 个分析类别提取模式。对于大型项目，Pass 1 会运行多次——每个领域组一次。在多栈项目中（如 Java 后端 + React 前端），后端和前端使用 **各自专用的分析提示**。
+**Pass 1** 是唯一读取源代码的阶段。它为每个领域选择代表性文件，跨 55–95 个分析类别提取模式。对于大型项目，Pass 1 会运行多次——每个领域组一次。在多栈项目中（如 Java 后端 + React 前端），后端和前端使用 **各自专用的分析提示**。
 
 **Pass 2** 将所有 Pass 1 结果合并为统一分析：通用模式（100% 共享）、多数模式（50%+ 共享）、领域特定模式、按严重度分级的反模式，以及横切关注点（命名、安全、数据库、测试、日志、性能）。
 
@@ -134,7 +293,7 @@ your-project/
 │
 ├── claudeos-core/                     ← 主要输出目录
 │   ├── generated/                     ← 分析 JSON + 动态提示
-│   ├── standard/                      ← 编码标准（15-17 个文件）
+│   ├── standard/                      ← 编码标准（15-19 个文件）
 │   ├── 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
 **Q：重新运行会怎样？**
 如果 Pass 1/2 的 JSON 已存在，则跳过。Pass 3 始终重新运行。旧版本可从 Master Plans 恢复。
 
+**Q：支持 Kotlin 吗？**
+支持。ClaudeOS-Core 从 `build.gradle.kts` 或 `build.gradle` 中的 kotlin 插件自动检测 Kotlin。使用专用的 `kotlin-spring` 模板进行 Kotlin 特定分析（data class、sealed class、协程、扩展函数、MockK 等）。
+
+**Q：CQRS / BFF 架构呢？**
+完全支持 Kotlin 多模块项目。ClaudeOS-Core 读取 `settings.gradle.kts`，从模块名检测模块类型（command、query、bff、integration），并将同一域的 Command/Query 模块分组。生成的标准包含 command controller 与 query controller 的独立规则、BFF/Feign 模式和模块间通信规范。
+
+**Q：Gradle 多模块 monorepo 呢？**
+ClaudeOS-Core 扫描所有子模块（`**/src/main/kotlin/**/*.kt`），不受嵌套深度限制。模块类型从命名规则推断（例如 `reservation-command-server` → 域: `reservation`，类型: `command`）。共享库（`shared-lib`、`integration-lib`）也会被检测。
+
 ---
 
 ## 模板结构
@@ -262,6 +431,7 @@ npx claudeos-core restore
 pass-prompts/templates/
 ├── common/                  # 共享头部/尾部
 ├── java-spring/             # Java / Spring Boot
+├── kotlin-spring/           # Kotlin / Spring Boot（CQRS、BFF、多模块）
 ├── 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#트러블슈팅)了解你的技术栈的检测模式。
+
+**Kotlin 项目「检测到 0 个域」** — 确保根目录有 `build.gradle.kts`，源文件在 `**/src/main/kotlin/` 下。多模块项目需要 `settings.gradle.kts` 包含 `include()` 语句。单模块 Kotlin 项目（无 `settings.gradle`）也受支持——从 `src/main/kotlin/` 下的包/类结构中提取域。
+
+**「语言检测为 java 而非 kotlin」** — 先检查根 build 文件，再检查最多 5 个子模块 build 文件。确保至少一个包含 `kotlin("jvm")` 或 `org.jetbrains.kotlin`。
+
+**「未检测到 CQRS」** — 架构检测依赖模块名中包含 `command` 和 `query` 关键字。
 
 ---