claudeos-core 2.3.1 → 2.4.0

package/README.vi.md

@@ -1,1015 +1,454 @@
 # ClaudeOS-Core
 
-**Công cụ duy nhất đọc mã nguồn trước, xác nhận stack và pattern bằng phân tích deterministic, sau đó tạo Claude Code rules phù hợp chính xác với dự án của bạn.**
+[![npm version](https://img.shields.io/npm/v/claudeos-core.svg?logo=npm&label=npm)](https://www.npmjs.com/package/claudeos-core)
+[![CI](https://img.shields.io/github/actions/workflow/status/claudeos-core/claudeos-core/test.yml?branch=master&logo=github&label=CI)](https://github.com/claudeos-core/claudeos-core/actions/workflows/test.yml)
+[![tests](https://img.shields.io/badge/tests-736%20passing-brightgreen?logo=node.js&logoColor=white)](https://github.com/claudeos-core/claudeos-core/actions/workflows/test.yml)
+[![node](https://img.shields.io/node/v/claudeos-core.svg?logo=node.js&logoColor=white&label=node)](https://nodejs.org/)
+[![license](https://img.shields.io/npm/l/claudeos-core.svg?color=blue)](LICENSE)
+[![downloads](https://img.shields.io/npm/dm/claudeos-core.svg?logo=npm&color=blue&label=downloads)](https://www.npmjs.com/package/claudeos-core)
+
+**Tự động sinh tài liệu Claude Code từ chính mã nguồn thực tế của bạn.** Một CLI phân tích tĩnh dự án rồi chạy pipeline Claude 4-pass để sinh `.claude/rules/`, standards, skills và guides — nhờ đó Claude Code tuân theo **các quy ước của dự án bạn**, không phải các quy ước chung chung.
 
 ```bash
 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.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)
+[🇺🇸 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)
 
 ---
 
-## Tại sao chọn ClaudeOS-Core?
-
-Mọi công cụ Claude Code khác hoạt động như sau:
-
-> **Con người mô tả dự án → LLM tạo tài liệu**
-
-ClaudeOS-Core hoạt động như sau:
-
-> **Code phân tích source → Code xây dựng prompt tùy chỉnh → LLM tạo tài liệu → Code xác minh đầu ra**
-
-Đây không phải là khác biệt nhỏ. Lý do quan trọng:
-
-### Vấn đề cốt lõi: LLM đoán. Code thì không.
+## Công cụ này là gì?
 
-Khi bạn yêu cầu Claude "phân tích dự án này", nó **đoán** stack, ORM, cấu trúc domain của bạn.
-Nó có thể thấy `spring-boot` trong `build.gradle` nhưng bỏ sót việc bạn dùng MyBatis (không phải JPA).
-Nó có thể phát hiện thư mục `user/` nhưng không nhận ra dự án của bạn dùng layer-first packaging (Pattern A), không phải domain-first (Pattern B).
+Bạn đang dùng Claude Code. Nó thông minh, nhưng nó không biết **các quy ước của dự án bạn**:
+- Đội của bạn dùng MyBatis, nhưng Claude lại sinh code JPA.
+- Wrapper của bạn là `ApiResponse.ok()`, nhưng Claude lại viết `ResponseEntity.success()`.
+- Package của bạn là `controller/order/`, nhưng Claude lại tạo `order/controller/`.
 
-**ClaudeOS-Core không đoán.** Trước khi Claude nhìn thấy dự án của bạn, Node.js code đã:
+Vì vậy bạn mất khá nhiều thời gian để sửa từng tệp được sinh ra.
 
-- Parse `build.gradle` / `package.json` / `pyproject.toml` và **xác nhận** stack, ORM, DB và package manager
-- Quét cấu trúc thư mục và **xác nhận** danh sách domain kèm số lượng file
-- Phân loại cấu trúc dự án vào một trong 5 pattern Java, Kotlin CQRS/BFF, hoặc Next.js App Router/FSD
-- Chia domain thành các nhóm có kích thước tối ưu phù hợp với context window của Claude
-- Lắp ráp prompt riêng cho stack với mọi sự thật đã xác nhận được chèn vào
+**ClaudeOS-Core khắc phục điều này.** Nó quét mã nguồn thực tế của bạn, xác định các quy ước, và viết một tập rule hoàn chỉnh vào `.claude/rules/` — thư mục mà Claude Code tự động đọc. Lần sau bạn nói *"Tạo CRUD cho orders"*, Claude sẽ tuân theo quy ước của bạn ngay từ lần đầu.
 
-Khi Claude nhận prompt, không còn gì phải đoán. Stack đã xác nhận. Domain đã xác nhận. Pattern cấu trúc đã xác nhận. Nhiệm vụ duy nhất của Claude là tạo tài liệu khớp với các **sự thật đã xác nhận** này.
-
-### Kết quả
-
-Các công cụ khác tạo tài liệu "tốt một cách chung chung".
-ClaudeOS-Core tạo tài liệu biết rằng dự án dùng `ApiResponse.ok()` (không phải `ResponseEntity.success()`), MyBatis XML mapper của bạn nằm ở `src/main/resources/mybatis/mappers/`, và package structure là `com.company.module.{domain}.controller` — vì nó đã đọc code thực tế của bạn.
-
-### Before & After
-
-**Không có ClaudeOS-Core** — bạn yêu cầu Claude Code tạo Order CRUD:
 ```
-❌ Dùng repository kiểu JPA (dự án của bạn dùng MyBatis)
-❌ Tạo ResponseEntity.success() (wrapper của bạn là ApiResponse.ok())
-❌ Đặt file vào order/controller/ (dự án của bạn dùng controller/order/)
-❌ Tạo comment tiếng Anh (team của bạn viết comment tiếng Việt)
-→ Bạn mất 20 phút sửa từng file đã tạo
+Trước:  Bạn → Claude Code → code "tốt nói chung" → sửa thủ công
+Sau:    Bạn → Claude Code → code khớp với dự án của bạn → dùng luôn
 ```
 
-**Có ClaudeOS-Core** — `.claude/rules/` đã chứa các pattern đã xác nhận của bạn:
-```
-✅ Tạo MyBatis mapper + XML (phát hiện từ build.gradle)
-✅ Dùng ApiResponse.ok() (trích xuất từ source thực tế của bạn)
-✅ Đặt file vào controller/order/ (Pattern A xác nhận bằng structure scan)
-✅ Comment tiếng Việt (--lang vi đã áp dụng)
-→ Code được tạo khớp ngay với convention của dự án
-```
-
-Sự khác biệt này được tích lũy. 10 task/ngày × 20 phút tiết kiệm = **hơn 3 giờ/ngày**.
-
 ---
 
-## Đảm bảo chất lượng sau khi sinh (v2.3.0)
-
-Sinh ra tài liệu chỉ là một nửa vấn đề. Nửa còn lại là **biết rằng output là đúng** — xuyên suốt 10 ngôn ngữ output, 11 template stack, và các dự án ở mọi kích thước. v2.3.0 thêm hai validator tất định chạy sau khi sinh và không phụ thuộc vào LLM tự kiểm tra.
-
-### `claude-md-validator` — bất biến cấu trúc
-
-Mỗi `CLAUDE.md` được sinh ra đều được kiểm tra đối chiếu với 25 bất biến cấu trúc sử dụng chỉ những tín hiệu không phụ thuộc ngôn ngữ: cú pháp markdown (`^## `, `^### `), tên file literal (`decision-log.md`, `failure-patterns.md` — không bao giờ được dịch), số section, số sub-section mỗi section, và số hàng bảng. Cùng một validator, từng byte một, sẽ đưa ra phán quyết giống nhau đối với `CLAUDE.md` được sinh ra bằng tiếng Anh, Hàn, Nhật, Việt, Hindi, Nga, Tây Ban Nha, Trung, Pháp, hoặc Đức.
-
-Đảm bảo xuyên ngôn ngữ được xác minh bằng các test fixture trong cả 10 ngôn ngữ, bao gồm các fixture bad-case trong 6 trong số các ngôn ngữ đó tạo ra chữ ký lỗi giống hệt nhau. Khi một bất biến thất bại trên một dự án tiếng Việt, cách sửa cũng giống như khi nó thất bại trên một dự án tiếng Đức.
-
-### `content-validator [10/10]` — xác minh tuyên bố path và tính nhất quán MANIFEST
-
-Đọc mọi tham chiếu path được bọc bởi backtick (`src/...`, `.claude/rules/...`, `claudeos-core/skills/...`) từ tất cả các file `.md` được sinh ra và xác minh chúng với file system thực. Bắt hai lớp thất bại của LLM mà không có công cụ nào phát hiện trước đây:
-
-- **`STALE_PATH`** — khi Pass 3 hoặc Pass 4 bịa ra một đường dẫn nghe có vẻ hợp lý nhưng không tồn tại. Các trường hợp điển hình: suy diễn `featureRoutePath.ts` từ một TypeScript constant có tên `FEATURE_ROUTE_PATH` khi file thực tế là `routePath.ts`; giả định `src/main.tsx` theo quy ước Vite trong một dự án multi-entry; giả định `src/__mocks__/handlers.ts` theo tài liệu MSW ngay cả khi dự án không có test nào.
-- **`MANIFEST_DRIFT`** — khi `claudeos-core/skills/00.shared/MANIFEST.md` đăng ký một skill mà `CLAUDE.md §6` không đề cập (hoặc ngược lại). Nhận diện layout orchestrator + sub-skills phổ biến, trong đó `CLAUDE.md §6` là điểm vào và `MANIFEST.md` là registry đầy đủ — các sub-skill được coi là được bao phủ thông qua orchestrator cha của chúng.
-
-Validator này được kết hợp với phòng ngừa ở giai đoạn prompt trong `pass3-footer.md` và `pass4.md`: các khối anti-pattern ghi lại các lớp hallucination cụ thể (tiền tố thư mục cha, các quy ước thư viện Vite/MSW/Vitest/Jest/RTL), và positive guidance rõ ràng về việc giới hạn phạm vi các rule theo thư mục khi một tên file cụ thể không có trong `pass3a-facts.md`.
-
-### Chạy validation trên bất kỳ dự án nào
-
-```bash
-npx claudeos-core health     # tất cả validator — một phán quyết go/no-go duy nhất
-npx claudeos-core lint       # chỉ bất biến cấu trúc CLAUDE.md (bất kỳ ngôn ngữ nào)
-```
-
+## Xem trên một dự án thật
+
+Chạy trên [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app) — Java 11 · Spring Boot 2.6 · MyBatis · SQLite · 187 source files. Kết quả: **75 generated files**, tổng thời gian **53 phút**, mọi validator ✅.
+
+<p align="center">
+  <img src="docs/assets/spring-boot-realworld-demo.gif" alt="ClaudeOS-Core init running on spring-boot-realworld-example-app — stack detection, 4-pass pipeline, validators, completion summary" width="769">
+</p>
+
+<details>
+<summary><strong>📺 Đầu ra terminal (bản text, để tìm kiếm và sao chép)</strong></summary>
+
+```text
+╔════════════════════════════════════════════════════╗
+║       ClaudeOS-Core — Bootstrap (4-Pass)          ║
+╚════════════════════════════════════════════════════╝
+    Project root: spring-boot-realworld-example-app
+    Language:     English (en)
+
+  [Phase 1] Detecting stack...
+    Language:    java 11
+    Framework:   spring-boot 2.6.3
+    Database:    sqlite
+    ORM:         mybatis
+    PackageMgr:  gradle
+
+  [Phase 2] Scanning structure...
+    Backend:     2 domains
+    Total:       2 domains
+    Package:     io.spring.infrastructure
+
+  [Phase 5] Active domains...
+    ✅ 00.core   ✅ 10.backend   ⏭️ 20.frontend
+    ✅ 30.security-db   ✅ 40.infra
+    ✅ 80.verification  ✅ 90.optional
+
+[4] Pass 1 — Deep analysis per domain group...
+    ✅ pass1-1.json created (5m 34s)
+    [█████░░░░░░░░░░░░░░░] 25% (1/4)
+
+[5] Pass 2 — Merging analysis results...
+    ✅ pass2-merged.json created (4m 22s)
+    [██████████░░░░░░░░░░] 50% (2/4)
+
+[6] Pass 3 — Generating all files...
+    🚀 Pass 3 split mode (3a → 3b → 3c → 3d-aux)
+    ✅ 3a complete (2m 57s)            — pass3a-facts.md (187-path allowlist)
+    ✅ 3b complete (18m 49s)           — CLAUDE.md + 19 standards + 20 rules
+    ✅ 3c complete (12m 35s)           — 13 skills + 9 guides
+    ✅ 3d-aux complete (3m 18s)        — database/ + mcp-guide/
+    🎉 Pass 3 split complete: 4/4 stages successful
+    [███████████████░░░░░] 75% (3/4)
+
+[7] Pass 4 — Memory scaffolding...
+    📦 Pass 4 staged-rules: 6 rule files moved to .claude/rules/
+    ✅ Pass 4 complete (5m)
+       📋 Gap-fill: all 12 expected files already present
+    [████████████████████] 100% (4/4)
+
+╔═══════════════════════════════════════╗
+║  ClaudeOS-Core — Health Checker       ║
+╚═══════════════════════════════════════╝
+  ✅ plan-validator         pass
+  ✅ sync-checker           pass
+  ✅ content-validator      pass
+  ✅ pass-json-validator    pass
+  ✅ All systems operational
+
+  [Lint] ✅ CLAUDE.md structure valid (25 checks)
+  [Content] ✅ All content validation passed
+            Total: 0 advisories, 0 notes
+
+╔════════════════════════════════════════════════════╗
+║  ✅ ClaudeOS-Core — Complete                       ║
+║   Files created:     75                           ║
+║   Domains analyzed:  1 group                      ║
+║   L4 scaffolded:     memory + rules               ║
+║   Output language:   English                      ║
+║   Total time:        53m 8s                       ║
+╚════════════════════════════════════════════════════╝
+```
+
+</details>
+
+<details>
+<summary><strong>📄 Trích đoạn <code>CLAUDE.md</code> được sinh (đầu ra thực tế)</strong></summary>
+
+```markdown
+## 4. Core Architecture
+
+### Core Patterns
+
+- **Hexagonal ports & adapters**: domain ports live in `io.spring.core.{aggregate}`
+  and are implemented by `io.spring.infrastructure.repository.MyBatis{Aggregate}Repository`.
+  The domain layer has zero MyBatis imports.
+- **CQRS-lite read/write split (same DB)**: write side goes through repository ports
+  + entities; read side is a separate `readservice` package whose `@Mapper`
+  interfaces return `*Data` DTOs directly (no entity hydration).
+- **No aggregator/orchestrator layer**: multi-source orchestration happens inside
+  application services (e.g., `ArticleQueryService`); there is no `*Aggregator`
+  class in the codebase.
+- **Application-supplied UUIDs**: entity constructors assign their own UUID; PK is
+  passed via `#{user.id}` on INSERT. The global
+  `mybatis.configuration.use-generated-keys=true` flag is dead config
+  (auto-increment is unused).
+- **JWT HS512 authentication**: `io.spring.infrastructure.service.DefaultJwtService`
+  is the sole token subject in/out; `io.spring.api.security.JwtTokenFilter`
+  extracts the token at the servlet layer.
+```
+
+Lưu ý: mọi luận điểm phía trên đều dựa trên mã nguồn thực — tên class, đường dẫn package, key cấu hình, và cờ dead-config đều do scanner trích xuất trước khi Claude viết tệp.
+
+</details>
+
+<details>
+<summary><strong>🛡️ Một rule thực tế được tự động nạp (<code>.claude/rules/10.backend/03.data-access-rules.md</code>)</strong></summary>
+
+````markdown
 ---
-
-## Stack Được Hỗ Trợ
-
-| Stack | Phát Hiện | Độ Sâu Phân Tích |
-|---|---|---|
-| **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** | `package.json` | 9 danh mục, 57 mục con |
-| **Node.js / NestJS** | `package.json` (`@nestjs/core`) | 10 danh mục, 68 mục con |
-| **Next.js / React** | `package.json`, `next.config.*`, hỗ trợ FSD | 9 danh mục, 55 mục con |
-| **Vue / Nuxt** | `package.json`, `nuxt.config.*`, Composition API | 9 danh mục, 58 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 |
-| **Node.js / Fastify** | `package.json` | 10 danh mục, 62 mục con |
-| **Vite / React SPA** | `package.json`, `vite.config.*` | 9 danh mục, 55 mục con |
-| **Angular** | `package.json`, `angular.json` | 12 danh mục, 78 mục con |
-
-Tự động phát hiện: ngôn ngữ & phiên bản, framework & phiên bản (bao gồm Vite như SPA framework), 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), monorepo (Turborepo, pnpm-workspace, Lerna, npm/yarn workspaces), **cấu hình runtime từ `.env.example`** (v2.2.0 — trích xuất port/host/API-target từ 16+ tên biến quy ước trên các framework Vite · Next.js · Nuxt · Angular · Node · Python).
-
-**Bạn không cần chỉ định gì cả. Tất cả được phát hiện tự động.**
-
-### Cấu hình runtime từ `.env` (v2.2.0)
-
-v2.2.0 bổ sung `lib/env-parser.js` để `CLAUDE.md` được sinh ra phản ánh những gì project thực sự khai báo, thay vì giá trị mặc định của framework.
-
-- **Thứ tự tìm kiếm**: `.env.example` (canonical, đã commit) → `.env.local.example` → `.env.sample` → `.env.template` → `.env` → `.env.local` → `.env.development`. Biến thể `.example` thắng vì đó là shape-of-truth trung lập của developer, không phải override local của một contributor cụ thể.
-- **Các quy ước biến port được nhận diện**: `VITE_PORT` / `VITE_DEV_PORT` / `VITE_DESKTOP_PORT` / `NEXT_PUBLIC_PORT` / `NUXT_PORT` / `NG_PORT` / `APP_PORT` / `SERVER_PORT` / `HTTP_PORT` / `DEV_PORT` / `FLASK_RUN_PORT` / `UVICORN_PORT` / `DJANGO_PORT` / `PORT` tổng quát. Tên đặc thù framework thắng `PORT` tổng quát khi cả hai cùng hiện diện.
-- **Host & API target**: `VITE_DEV_HOST` / `VITE_API_TARGET` / `NEXT_PUBLIC_API_URL` / `NUXT_PUBLIC_API_BASE` / `BACKEND_URL` / `PROXY_TARGET` v.v.
-- **Độ ưu tiên**: Spring Boot `application.yml` `server.port` vẫn thắng (config framework-native), rồi đến port khai báo trong `.env`, cuối cùng mới fallback về default của framework (Vite 5173, Next.js 3000, Django 8000, v.v.).
-- **Redact biến nhạy cảm**: giá trị của các biến khớp pattern `PASSWORD` / `SECRET` / `TOKEN` / `API_KEY` / `ACCESS_KEY` / `PRIVATE_KEY` / `CREDENTIAL` / `JWT_SECRET` / `CLIENT_SECRET` / `SESSION_SECRET` / `BEARER` / `SALT` được thay bằng `***REDACTED***` trước khi tới bất kỳ generator downstream nào. Defense-in-depth chống secret bị commit nhầm vào `.env.example`. `DATABASE_URL` được whitelist tường minh để giữ back-compat cho việc nhận diện DB của stack-detector.
-
-### 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 qua thư mục `service/`, `dao/`, `aggregator/`, `facade/`, `usecase/`, `orchestrator/`, `mapper/`, `repository/`. Bỏ qua: `common`, `config`, `util`, `core`, `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 14 module |
-| 2 | Phát hiện kiểu 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 | Gom 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 |
-
-Các kiểu module được hỗ trợ: `command`, `query`, `bff`, `integration`, `standalone`, `library`. Các thư viện dùng chung (`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/*/`
-- **Phân tách RSC/Client**: phát hiện pattern `client.tsx`, theo dõi phân tách Server/Client component
-- **Đường dẫn lồng nhau không chuẩn**: Phát hiện pages, components và các FSD layer dưới đường dẫn `src/*/` (ví dụ: `src/admin/pages/dashboard/`, `src/admin/components/form/`, `src/admin/features/billing/`)
-- **Phát hiện chia tách Platform/tier (v2.0.0)**: Nhận diện layout `src/{platform}/{subapp}/` — `{platform}` có thể là keyword device/target (`desktop`, `pc`, `web`, `mobile`, `mc`, `mo`, `sp`, `tablet`, `tab`, `pwa`, `tv`, `ctv`, `ott`, `watch`, `wear`) hoặc keyword access-tier (`admin`, `cms`, `backoffice`, `back-office`, `portal`). Sinh một domain cho mỗi cặp `(platform, subapp)` với tên `{platform}-{subapp}` kèm số đếm routes/components/layouts/hooks riêng cho từng domain. Chạy đồng thời trên Angular, Next.js, React và Vue (glob đa đuôi `{tsx,jsx,ts,js,vue}`). Yêu cầu ≥2 file nguồn cho mỗi subapp để tránh domain nhiễu 1-file.
-- **Monorepo platform split (v2.0.0)**: Platform scan cũng khớp với `{apps,packages}/*/src/{platform}/{subapp}/` (Turborepo/pnpm workspace có `src/`) và `{apps,packages}/{platform}/{subapp}/` (workspace không có wrapper `src/`).
-- **Fallback E — routes-file (v2.0.0)**: Khi scanner chính + Fallback A–D đều trả về 0, glob `**/routes/*.{tsx,jsx,ts,js,vue}` và gom nhóm theo tên thư mục cha của `routes`. Bắt các dự án React Router file-routing (CRA/Vite + `react-router`) không khớp với `page.tsx` của Next.js hoặc layout FSD. Tên cha chung chung (`src`, `app`, `pages`) được lọc bỏ.
-- **Config fallback**: Phát hiện Next.js/Vite/Nuxt từ file cấu hình khi không có trong `package.json` (hỗ trợ monorepo)
-- **Deep directory fallback**: Đối với dự án React/CRA/Vite/Vue/RN, quét `**/components/*/`, `**/views/*/`, `**/screens/*/`, `**/containers/*/`, `**/pages/*/`, `**/routes/*/`, `**/modules/*/`, `**/domains/*/` ở bất kỳ độ sâu nào
-- **Danh sách bỏ qua dùng chung (v2.0.0)**: Tất cả scanner chia sẻ `BUILD_IGNORE_DIRS` (`node_modules`, `build`, `dist`, `out`, `.next`, `.nuxt`, `.svelte-kit`, `.angular`, `.turbo`, `.cache`, `.parcel-cache`, `coverage`, `storybook-static`, `.vercel`, `.netlify`) và `TEST_FILE_IGNORE` (spec/test/stories/e2e/cy + `__snapshots__`/`__tests__`) để build output và test fixture không làm phồng số file của từng domain.
-
-### Scanner Overrides (v2.0.0)
-
-Thả tùy chọn `.claudeos-scan.json` tại root của dự án để mở rộng giá trị mặc định của scanner mà không cần chỉnh sửa toolkit. Tất cả các trường đều **cộng dồn** — các mục của người dùng mở rộng giá trị mặc định, không thay thế:
-
-```json
-{
-  "frontendScan": {
-    "platformKeywords": ["kiosk"],
-    "skipSubappNames": ["legacy"],
-    "minSubappFiles": 3
-  }
-}
-```
-
-| Trường | Mặc định | Mục đích |
-|---|---|---|
-| `platformKeywords` | danh sách built-in ở trên | Các keyword `{platform}` bổ sung cho platform scan (ví dụ: `kiosk`, `vr`, `embedded`) |
-| `skipSubappNames` | chỉ các thư mục cấu trúc | Các tên subapp bổ sung để loại khỏi việc sinh domain của platform scan |
-| `minSubappFiles` | `2` | Ghi đè số file tối thiểu cần có trước khi một subapp trở thành domain |
-
-Thiếu file hoặc JSON bị lỗi → âm thầm fallback về mặc định (không crash). Sử dụng điển hình: opt-in một viết tắt ngắn (`adm`, `bo`) mà danh sách built-in loại vì quá mơ hồ, hoặc nâng `minSubappFiles` cho monorepo nhiễu.
-
+paths:
+  - "**/*"
 ---
 
-## Bắt Đầu Nhanh
-
-### Yêu cầu trước
+# Data Access Rules
 
-- **Node.js** v18+
-- **Claude Code CLI** (đã cài đặt & xác thực)
+## XML-only SQL
+- Every SQL statement lives in `src/main/resources/mapper/*.xml`.
+  NO `@Select` / `@Insert` / `@Update` / `@Delete` annotations on `@Mapper` methods.
+- Each `@Mapper` interface has exactly one XML file at
+  `src/main/resources/mapper/{InterfaceName}.xml`.
+- `<mapper namespace="...">` MUST be the fully qualified Java interface name.
+  The single existing exception is `TransferData.xml` (free-form `transfer.data`).
 
-### Cài đặt
-
-```bash
-cd /your/project/root
-
-# Cách A: npx (khuyến nghị — không cần cài đặt)
-npx claudeos-core init
+## Dynamic SQL
+- `<if>` predicates MUST guard both null and empty:
+  `<if test="X != null and X != ''">`. Empty-only is the existing HIGH-severity bug pattern.
+- Prefer `LIMIT n OFFSET m` over MySQL-style `LIMIT m, n`.
 
-# Cách B: cài đặt global
-npm install -g claudeos-core
-claudeos-core init
+## Examples
 
-# Cách C: project devDependency
-npm install --save-dev claudeos-core
-npx claudeos-core init
-
-# Cách D: git clone (để phát triển/đóng góp)
-git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
-
-# Đa nền tảng (PowerShell, CMD, Bash, Zsh — mọi terminal)
-node claudeos-core-tools/bin/cli.js init
-
-# Linux/macOS (chỉ Bash)
-bash claudeos-core-tools/bootstrap.sh
+✅ Correct:
+```xml
+<update id="update">
+  UPDATE articles
+  <set>
+    <if test="article.title != null and article.title != ''">title = #{article.title},</if>
+    updated_at = #{article.updatedAt}
+  </set>
+  WHERE id = #{article.id}
+</update>
 ```
 
-### Ngôn Ngữ Đầu Ra (10 ngôn ngữ)
-
-Khi chạy `init` không có `--lang`, selector tương tác sẽ hiện ra — dùng phím mũi tên hoặc phím số để chọn:
-
-```
-╔══════════════════════════════════════════════════╗
-║  Select generated document language (required)   ║
-╚══════════════════════════════════════════════════╝
-
-  Các file được tạo (CLAUDE.md, Standards, Rules,
-  Skills, Guides) sẽ được viết bằng Tiếng Việt.
-
-     1. en     — English
-     2. ko     — 한국어 (Korean)
-     3. zh-CN  — 简体中文 (Chinese Simplified)
-     4. ja     — 日本語 (Japanese)
-     5. es     — Español (Spanish)
-  ❯  6. vi     — Tiếng Việt (Vietnamese)
-     7. hi     — हिन्दी (Hindi)
-     8. ru     — Русский (Russian)
-     9. fr     — Français (French)
-    10. de     — Deutsch (German)
-
-  ↑↓ Move  1-0 Jump  Enter Select  ESC Cancel
+❌ Incorrect:
+```xml
+<mapper namespace="article.mapper">          <!-- NO — namespace MUST be FQCN -->
 ```
+````
 
-Mô tả sẽ đổi sang ngôn ngữ được chọn khi bạn điều hướng. Để bỏ qua selector, truyền `--lang` trực tiếp:
+Glob `paths: ["**/*"]` có nghĩa là Claude Code tự động nạp rule này mỗi khi bạn chỉnh bất kỳ tệp nào trong dự án. Các ví dụ ✅/❌ được lấy thẳng từ chính các quy ước và mẫu lỗi đã có trong codebase này.
 
-```bash
-npx claudeos-core init --lang ko    # Korean
-npx claudeos-core init --lang ja    # Japanese
-npx claudeos-core init --lang en    # English (mặc định)
-```
-
-> **Lưu ý:** Cài đặt này chỉ áp dụng cho ngôn ngữ của các file tài liệu được tạo. Phân tích code (Pass 1–2) luôn chạy bằng tiếng Anh; output được tạo (Pass 3) được viết bằng ngôn ngữ bạn chọn. Các ví dụ code bên trong file được tạo vẫn giữ nguyên cú pháp ngôn ngữ lập trình gốc.
-
-Vậy thôi. Sau 10 phút (dự án nhỏ) đến 2 giờ (monorepo 60+ domain), tất cả tài liệu được tạo và sẵn sàng sử dụng. CLI hiển thị thanh tiến trình kèm phần trăm, thời gian đã trôi qua và ETA cho mỗi pass. Xem [Tự Động Mở Rộng Theo Kích Thước Dự Án](#tự-động-mở-rộng-theo-kích-thước-dự-án) để biết thời gian chi tiết theo kích thước dự án.
+</details>
 
-### Cài Đặt Thủ Công Từng Bước
+<details>
+<summary><strong>🧠 Hạt mầm <code>decision-log.md</code> tự sinh (trích đoạn thực tế)</strong></summary>
 
-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 bị lỗi ở bước nào đó — bạn có thể chạy từng giai đoạn thủ công. Cách này cũng hữu ích để hiểu cách ClaudeOS-Core hoạt động bên trong.
+```markdown
+## 2026-04-26 — CQRS-lite read/write split inside the persistence layer
 
-#### 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 ..
+- **Context:** Writes go through `core.*Repository` port → `MyBatis*Repository`
+  adapter → `io.spring.infrastructure.mybatis.mapper.{Aggregate}Mapper`.
+  Reads bypass the domain port: application service →
+  `io.spring.infrastructure.mybatis.readservice.{Concept}ReadService` directly,
+  returning flat `*Data` DTOs from `io.spring.application.data.*`.
+- **Options considered:** Single repository surface returning hydrated entities
+  for both reads and writes.
+- **Decision:** Same database, two `@Mapper` packages — `mapper/` (write side,
+  operates on core entities) and `readservice/` (read side, returns `*Data` DTOs).
+  Read DTOs avoid entity hydration overhead.
+- **Consequences:** Reads are NOT routed through the domain port — this is
+  intentional, not a bug. Application services may inject both a `*Repository`
+  (writes) and one or more `*ReadService` interfaces (reads) at the same time.
+  Do NOT add hydrate-then-map glue in the read path.
 ```
 
-#### Step 2: Tạo cấu trúc thư mục
-
-```bash
-# Rules (v2.0.0: thêm 60.memory)
-mkdir -p .claude/rules/{00.core,10.backend,20.frontend,30.security-db,40.infra,50.sync,60.memory}
-
-# 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, Database, MCP, Generated, Memory (v2.0.0: thêm memory; v2.1.0: bỏ plan)
-mkdir -p claudeos-core/guide/{01.onboarding,02.usage,03.troubleshooting,04.architecture}
-mkdir -p claudeos-core/{database,mcp-guide,generated,memory}
-```
-
-> **Lưu ý v2.1.0:** Thư mục `claudeos-core/plan/` không còn được tạo nữa. Việc tạo master plan đã bị loại bỏ vì master plan là backup nội bộ mà Claude Code không đọc lúc runtime, và việc tổng hợp chúng đã gây ra lỗi `Prompt is too long`. Dùng `git` để backup/restore thay thế.
-
-#### Step 3: Chạy plan-installer (phân tích dự án)
+Pass 4 gieo `decision-log.md` bằng các quyết định kiến trúc được trích từ `pass2-merged.json`, để các phiên sau ghi nhớ *vì sao* codebase trông như vậy — không chỉ *trông như thế nào*.
 
-Lệnh này quét dự án, phát hiện stack, tìm domain, chia chúng thành các nhóm và tạo prompt.
+</details>
 
-```bash
-node claudeos-core-tools/plan-installer/index.js
-```
-
-**Output (trong `claudeos-core/generated/`):**
-- `project-analysis.json` — stack, domain, thông tin frontend đã phát hiện
-- `domain-groups.json` — các nhóm domain cho Pass 1
-- `pass1-backend-prompt.md` / `pass1-frontend-prompt.md` — prompt phân tích
-- `pass2-prompt.md` — prompt merge
-- `pass3-prompt.md` — template prompt Pass 3 với block "Read Once, Extract Facts" Phase 1 được thêm vào đầu (Rules A–E). Pipeline tự động chia Pass 3 thành nhiều stage lúc runtime; template này dùng cho từng stage.
-- `pass3-context.json` — slim project summary (< 5 KB, xây sau Pass 2) mà prompt Pass 3 ưu tiên hơn `pass2-merged.json` đầy đủ (v2.1.0)
-- `pass4-prompt.md` — prompt L4 memory scaffolding (v2.0.0; dùng cùng `staging-override.md` cho ghi rule `60.memory/`)
-
-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 (mỗi nhóm domain)
+## Quick Start
 
-Chạy Pass 1 cho mỗi nhóm domain. Kiểm tra `domain-groups.json` để biết số lượng nhóm.
+**Yêu cầu trước:** Node.js 18+, [Claude Code](https://docs.anthropic.com/en/docs/claude-code) đã cài đặt và xác thực.
 
 ```bash
-# Kiểm tra có bao nhiêu nhóm
-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)'));
-"
-
-# Chạy Pass 1 cho mỗi nhóm (thay domain và số nhóm)
-# Lưu ý: v1.6.1+ dùng Node.js String.replace() thay vì perl — không còn
-# yêu cầu perl, và ngữ nghĩa replacement-function ngăn chặn regex injection
-# từ các ký tự $/&/$1 có thể xuất hiện trong tên domain.
-#
-# Cho nhóm 1:
-DOMAIN_LIST="user, order, product" PASS_NUM=1 node -e "
-  const fs = require('fs');
-  const tpl = fs.readFileSync('claudeos-core/generated/pass1-backend-prompt.md','utf-8');
-  const out = tpl
-    .replace(/\{\{DOMAIN_GROUP\}\}/g, () => process.env.DOMAIN_LIST)
-    .replace(/\{\{PASS_NUM\}\}/g, () => process.env.PASS_NUM);
-  process.stdout.write(out);
-" | claude -p --dangerously-skip-permissions
-
-# Cho nhóm 2 (nếu có):
-DOMAIN_LIST="payment, system, delivery" PASS_NUM=2 node -e "
-  const fs = require('fs');
-  const tpl = fs.readFileSync('claudeos-core/generated/pass1-backend-prompt.md','utf-8');
-  const out = tpl
-    .replace(/\{\{DOMAIN_GROUP\}\}/g, () => process.env.DOMAIN_LIST)
-    .replace(/\{\{PASS_NUM\}\}/g, () => process.env.PASS_NUM);
-  process.stdout.write(out);
-" | claude -p --dangerously-skip-permissions
-
-# Với nhóm frontend, đổi pass1-backend-prompt.md → pass1-frontend-prompt.md
-```
+# 1. Vào thư mục gốc dự án
+cd my-spring-boot-project
 
-**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 — Merge kết quả phân tích
+# 2. Chạy init (lệnh này phân tích code và yêu cầu Claude viết rules)
+npx claudeos-core init
 
-```bash
-cat claudeos-core/generated/pass2-prompt.md \
-  | claude -p --dangerously-skip-permissions
+# 3. Xong. Mở Claude Code và bắt đầu code — rules đã được nạp sẵn.
 ```
 
-**Xác minh:** `claudeos-core/generated/pass2-merged.json` phải tồn tại với 9+ top-level key.
-
-#### Step 6: Pass 3 — Tạo toàn bộ tài liệu (chia thành nhiều stage)
-
-**Lưu ý v2.1.0:** Pass 3 **luôn chạy ở chế độ split** bởi pipeline tự động. Mỗi stage là một lời gọi `claude -p` riêng biệt với context window mới, nên tràn output do tích lũy không thể xảy ra về mặt cấu trúc bất kể kích thước dự án. Template `pass3-prompt.md` được lắp ráp theo từng stage với một directive `STAGE:` chỉ cho Claude biết tập con file nào cần phát ra. Với chế độ thủ công, đường đơn giản nhất vẫn là đưa toàn bộ template và để Claude tạo mọi thứ trong một lời gọi — nhưng điều này chỉ đáng tin cậy trên dự án nhỏ (≤5 domain). Cho dự án lớn hơn, hãy dùng `npx claudeos-core init` để split runner xử lý điều phối stage.
-
-**Chế độ lời gọi đơn (chỉ cho dự án nhỏ, ≤5 domain):**
+**Bạn sẽ có** sau khi `init` hoàn tất:
 
-```bash
-cat claudeos-core/generated/pass3-prompt.md \
-  | claude -p --dangerously-skip-permissions
 ```
+your-project/
+├── .claude/
+│   └── rules/                    ← Tự động nạp bởi Claude Code
+│       ├── 00.core/              (rules chung — naming, kiến trúc)
+│       ├── 10.backend/           (rules backend stack, nếu có)
+│       ├── 20.frontend/          (rules frontend stack, nếu có)
+│       ├── 30.security-db/       (quy ước bảo mật & DB)
+│       ├── 40.infra/             (env, logging, CI/CD)
+│       ├── 50.sync/              (nhắc đồng bộ doc — chỉ rules)
+│       ├── 60.memory/            (memory rules — Pass 4, chỉ rules)
+│       ├── 70.domains/{type}/    (rules theo domain, type = backend|frontend)
+│       └── 80.verification/      (chiến lược test + nhắc xác minh build)
+├── claudeos-core/
+│   ├── standard/                 ← Tài liệu tham chiếu (mirror cấu trúc category)
+│   │   ├── 00.core/              (project overview, kiến trúc, naming)
+│   │   ├── 10.backend/           (reference backend — nếu có backend stack)
+│   │   ├── 20.frontend/          (reference frontend — nếu có frontend stack)
+│   │   ├── 30.security-db/       (reference bảo mật & DB)
+│   │   ├── 40.infra/             (reference env / logging / CI-CD)
+│   │   ├── 70.domains/{type}/    (reference theo domain)
+│   │   ├── 80.verification/      (reference build / startup / testing — chỉ standard)
+│   │   └── 90.optional/          (mở rộng riêng cho stack — chỉ standard)
+│   ├── skills/                   (mẫu tái sử dụng mà Claude có thể áp dụng)
+│   ├── guide/                    (hướng dẫn how-to cho các tác vụ thường gặp)
+│   ├── database/                 (tổng quan schema, hướng dẫn migration)
+│   ├── mcp-guide/                (ghi chú tích hợp MCP)
+│   └── memory/                   (decision log, failure patterns, compaction)
+└── CLAUDE.md                     (chỉ mục Claude đọc đầu tiên)
+```
+
+Các category dùng chung tiền tố số giữa `rules/` và `standard/` đại diện cho cùng một mảng khái niệm (ví dụ: `10.backend` rules ↔ `10.backend` standards). Category chỉ-rules: `50.sync` (nhắc đồng bộ doc) và `60.memory` (Pass 4 memory). Category chỉ-standard: `90.optional` (mở rộng riêng stack, không cưỡng chế). Mọi tiền tố khác (`00`, `10`, `20`, `30`, `40`, `70`, `80`) xuất hiện ở CẢ `rules/` và `standard/`. Giờ Claude Code đã hiểu dự án của bạn.
 
-**Chế độ từng stage (khuyến nghị cho mọi kích thước dự án):**
-
-Pipeline tự động chạy các stage sau. Danh sách stage:
-
-| Stage | Ghi | Ghi chú |
-|---|---|---|
-| `3a` | `pass3a-facts.md` (fact sheet đã chắt lọc 5–10 KB) | Đọc `pass2-merged.json` một lần; stage sau tham chiếu file này |
-| `3b-core` | `CLAUDE.md`, `standard/` chung, `.claude/rules/` chung | File xuyên dự án; không output đặc thù domain |
-| `3b-1..N` | `standard/60.domains/*.md` đặc thù domain + rule domain | Batch ≤15 domain mỗi stage (tự động chia ở ≥16 domain) |
-| `3c-core` | `guide/` (9 file), `skills/00.shared/MANIFEST.md`, orchestrator `skills/*/` | Skill chung và tất cả guide hướng người dùng |
-| `3c-1..N` | Sub-skill domain dưới `skills/20.frontend-page/scaffold-page-feature/` | Batch ≤15 domain mỗi stage |
-| `3d-aux` | `database/`, `mcp-guide/` | Kích thước cố định, không phụ thuộc số domain |
-
-Cho dự án 1–15 domain, điều này mở rộng thành 4 stage (`3a`, `3b-core`, `3c-core`, `3d-aux` — không chia batch). Cho 16–30 domain, mở rộng thành 8 stage (`3b` và `3c` mỗi cái chia thành 2 batch). Xem [Tự Động Mở Rộng Theo Kích Thước Dự Án](#tự-động-mở-rộng-theo-kích-thước-dự-án) để có bảng đầy đủ.
-
-**Xác minh:** `CLAUDE.md` phải tồn tại ở thư mục gốc dự án, và marker `claudeos-core/generated/pass3-complete.json` phải được ghi. Ở chế độ split, marker chứa `mode: "split"` và một mảng `groupsCompleted` liệt kê mọi stage đã hoàn thành — logic partial-marker dùng thông tin này để resume từ stage đúng sau khi crash thay vì bắt đầu lại từ `3a` (sẽ nhân đôi chi phí token).
-
-> **Lưu ý staging:** Pass 3 ghi các file rule vào `claudeos-core/generated/.staged-rules/` trước vì chính sách sensitive-path của Claude Code chặn ghi trực tiếp vào `.claude/`. Pipeline tự động xử lý việc di chuyển sau mỗi stage. Nếu bạn chạy một stage thủ công, bạn cần tự di chuyển cây staged: `mv claudeos-core/generated/.staged-rules/* .claude/rules/` (giữ nguyên subpath).
-
-#### Step 7: Pass 4 — Memory scaffolding
-
-```bash
-cat claudeos-core/generated/pass4-prompt.md \
-  | claude -p --dangerously-skip-permissions
-```
+---
 
-**Xác minh:** `claudeos-core/memory/` phải chứa 4 file (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`), `.claude/rules/60.memory/` phải chứa 4 file rule, và `CLAUDE.md` giờ phải có mục `## Memory (L4)` được append. Marker: `claudeos-core/generated/pass4-memory.json`.
+## Dành cho ai?
 
-> **Gap-fill v2.1.0:** Pass 4 cũng đảm bảo `claudeos-core/skills/00.shared/MANIFEST.md` tồn tại. Nếu Pass 3c bỏ sót (có thể xảy ra ở các dự án ít skill vì template stack `pass3.md` liệt kê `MANIFEST.md` là mục tiêu tạo mà không đánh dấu REQUIRED), gap-fill tạo stub tối thiểu để `.claude/rules/50.sync/02.skills-sync.md` (đường dẫn v2.2.0 — số lượng rule sync giảm từ 3 xuống 2, `03` trở thành `02`) luôn có tham chiếu hợp lệ. Idempotent: bỏ qua nếu file đã có nội dung thực (>20 ký tự).
+| Bạn là... | Công cụ này giúp bạn... |
+|---|---|
+| **Dev solo** đang khởi tạo dự án mới với Claude Code | Bỏ qua hoàn toàn giai đoạn "dạy Claude quy ước của tôi" |
+| **Team lead** duy trì chuẩn dùng chung | Tự động hóa phần tẻ nhạt: giữ `.claude/rules/` luôn cập nhật |
+| **Đã dùng Claude Code** nhưng mệt mỏi vì sửa code được sinh | Khiến Claude tuân theo mẫu của BẠN, không phải mẫu "tốt nói chung" |
 
-> **Lưu ý:** Nếu `claude -p` lỗi hoặc thiếu `pass4-prompt.md`, pipeline tự động sẽ fallback về scaffold tĩnh qua `lib/memory-scaffold.js` (có dịch qua Claude khi `--lang` khác tiếng Anh). Fallback tĩnh chỉ chạy bên trong `npx claudeos-core init` — chế độ thủ công yêu cầu Pass 4 thành công.
+**Không phù hợp nếu:** bạn muốn một bundle preset agents/skills/rules dạng one-size-fits-all chạy được ngay từ ngày đầu mà không cần bước scan (xem [docs/vi/comparison.md](docs/vi/comparison.md) để biết công cụ nào hợp với việc gì), hoặc dự án của bạn chưa khớp với một trong các [stack được hỗ trợ](#supported-stacks).
 
-#### Step 8: Chạy verification tools
+---
 
-```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
+## Hoạt động thế nào?
 
-# Chạy tất cả kiểm tra
-node claudeos-core-tools/health-checker/index.js
+ClaudeOS-Core đảo ngược workflow Claude Code thông thường:
 
-# Hoặc chạy từng kiểm tra:
-node claudeos-core-tools/plan-validator/index.js --check # Plan ↔ disk consistency
-node claudeos-core-tools/sync-checker/index.js          # File chưa đăng ký/orphan
-node claudeos-core-tools/content-validator/index.js     # Kiểm tra chất lượng file (bao gồm mục memory/ [9/9])
-node claudeos-core-tools/pass-json-validator/index.js   # Kiểm tra JSON Pass 1–4 + completion marker
 ```
-
-#### Step 9: Xác minh kết quả
-
-```bash
-# Đếm số file được tạo
-find .claude claudeos-core -type f | grep -v node_modules | grep -v '/generated/' | wc -l
-
-# Kiểm tra CLAUDE.md
-head -30 CLAUDE.md
-
-# Kiểm tra một file standard
-cat claudeos-core/standard/00.core/01.project-overview.md | head -20
-
-# Kiểm tra rules
-ls .claude/rules/*/
+Thông thường:  Bạn mô tả dự án → Claude đoán stack → Claude viết doc
+Công cụ này:   Code đọc stack → Code đưa sự kiện đã xác nhận cho Claude → Claude viết doc từ sự kiện
 ```
 
-> **Mẹo:** Nếu bước nào đó lỗi, bạn có thể sửa và chạy lại đúng 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. Dùng `npx claudeos-core init --force` để xóa kết quả trước và bắt đầu lại từ đầu.
-
-### Bắt Đầu Sử Dụng
+Ý tưởng then chốt: **một scanner Node.js đọc mã nguồn của bạn trước** (deterministic, không AI), sau đó pipeline Claude 4-pass viết tài liệu, bị ràng buộc bởi những gì scanner tìm thấy. Claude không thể bịa ra đường dẫn hay framework không thực sự có trong code.
 
-```
-# Trong Claude Code — chỉ cần hỏi tự nhiên:
-"Tạo CRUD cho domain order"
-"Thêm API xác thực người dùng"
-"Refactor code này khớp với pattern dự án"
-
-# Claude Code tự động tham chiếu Standards, Rules và Skills đã tạo.
-```
+Xem kiến trúc đầy đủ tại [docs/vi/architecture.md](docs/vi/architecture.md).
 
 ---
 
-## Cách Hoạt Động — 4-Pass Pipeline
-
-```
-npx claudeos-core init
-    │
-    ├── [1] npm install                        ← Dependencies (~10s)
-    ├── [2] Cấu trúc thư mục                   ← Tạo folder (~1s)
-    ├── [3] plan-installer (Node.js)           ← Quét dự án (~5s)
-    │       ├── Tự phát hiện stack (multi-stack aware)
-    │       ├── Trích domain list (tag: backend/frontend)
-    │       ├── Chia thành domain group (theo kiểu)
-    │       ├── Xây pass3-context.json (slim summary, v2.1.0)
-    │       └── Chọn prompt theo stack (theo kiểu)
-    │
-    ├── [4] Pass 1 × N  (claude -p)            ← Phân tích code sâu (~2-8min)
-    │       ├── ⚙️ Backend group → prompt backend
-    │       └── 🎨 Frontend group → prompt frontend
-    │
-    ├── [5] Pass 2 × 1  (claude -p)            ← Merge phân tích (~1min)
-    │       └── Tổng hợp TẤT CẢ kết quả Pass 1 vào pass2-merged.json
-    │
-    ├── [6] Pass 3 (split mode, v2.1.0)        ← Tạo mọi thứ
-    │       │
-    │       ├── 3a     × 1  (claude -p)        ← Trích xuất fact (~5-10min)
-    │       │       └── Đọc pass2-merged.json một lần → pass3a-facts.md
-    │       │
-    │       ├── 3b-core × 1  (claude -p)       ← CLAUDE.md + standard/rules chung
-    │       ├── 3b-1..N × N  (claude -p)       ← Standard/rules domain (≤15 domain/batch)
-    │       │
-    │       ├── 3c-core × 1  (claude -p)       ← Guides + skill chung + MANIFEST.md
-    │       ├── 3c-1..N × N  (claude -p)       ← Sub-skill domain (≤15 domain/batch)
-    │       │
-    │       └── 3d-aux  × 1  (claude -p)       ← Stub database/ + mcp-guide/
-    │
-    ├── [7] Pass 4 × 1  (claude -p)            ← Memory scaffolding (~30s-5min)
-    │       ├── Seed memory/ (decision-log, failure-patterns, …)
-    │       ├── Tạo rules 60.memory/
-    │       ├── Append mục "Memory (L4)" vào CLAUDE.md
-    │       └── Gap-fill: đảm bảo skills/00.shared/MANIFEST.md tồn tại (v2.1.0)
-    │
-    └── [8] Xác minh                           ← Tự chạy health checker
-```
-
-### Tại sao 4 Pass?
-
-**Pass 1** là pass duy nhất đọc mã nguồn của bạn. Nó chọn các file đại diện cho mỗi domain và trích xuất pattern qua 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 lần cho một nhóm domain. Với dự án multi-stack (ví dụ Java backend + React frontend), domain backend và frontend dùng **prompt phân tích khác nhau** phù hợp từng stack.
+## Supported Stacks
 
-**Pass 2** merge tất cả kết quả Pass 1 thành phân tích thống nhất: pattern chung (100% share), pattern đa số (50%+ share), pattern đặc thù domain, anti-pattern theo mức độ nghiêm trọng và các mối quan tâm cross-cutting (naming, security, DB, testing, logging, performance). Kết quả backend và frontend được merge cùng nhau.
+12 stack, tự động phát hiện từ tệp dự án:
 
-**Pass 3** (split mode, v2.1.0) nhận phân tích đã merge và tạo toàn bộ hệ sinh thái file (CLAUDE.md, rules, standards, skills, guides) qua nhiều lời gọi `claude -p` tuần tự. Insight quan trọng là tràn output do tích lũy không thể dự đoán từ kích thước input: Pass 3 lời-gọi-đơn hoạt động tốt trên dự án 2 domain và thất bại nhất quán ở ~5 domain, và ranh giới thất bại thay đổi tùy theo mức độ dài dòng của mỗi file. Split mode né hoàn toàn vấn đề này — mỗi stage bắt đầu với context window mới và ghi một tập con file có giới hạn. Tính nhất quán xuyên stage (vốn là lợi thế chính của phương pháp lời-gọi-đơn) được bảo tồn bởi `pass3a-facts.md`, một fact sheet đã chắt lọc 5–10 KB mà mọi stage sau tham chiếu.
+**Backend:** Java/Spring Boot · Kotlin/Spring Boot · Node/Express · Node/Fastify · Node/NestJS · Python/Django · Python/FastAPI · Python/Flask
 
-Template prompt Pass 3 cũng bao gồm **block Phase 1 "Read Once, Extract Facts"** với năm rule ràng buộc thêm khối lượng output:
+**Frontend:** Node/Next.js · Node/Vite · Angular · Vue/Nuxt
 
-- **Rule A** — Tham chiếu bảng fact; không đọc lại `pass2-merged.json`.
-- **Rule B** — Ghi file idempotent (bỏ qua nếu target đã có nội dung thực), giúp Pass 3 có thể chạy lại an toàn sau khi gián đoạn.
-- **Rule C** — Tính nhất quán xuyên file được đảm bảo qua bảng fact như single source of truth.
-- **Rule D** — Output cô đọng: một dòng (`[WRITE]`/`[SKIP]`) giữa các lần ghi file, không nhắc lại bảng fact, không echo nội dung file.
-- **Rule E** — Kiểm tra idempotent theo batch: một `Glob` lúc bắt đầu PHASE 2 thay vì gọi `Read` từng target.
+Dự án đa-stack (ví dụ: Spring Boot backend + Next.js frontend) hoạt động ngay không cần cấu hình.
 
-Trong **v2.2.0**, Pass 3 cũng inline một CLAUDE.md scaffold deterministic (`pass-prompts/templates/common/claude-md-scaffold.md`) vào prompt. Điều này cố định tiêu đề và thứ tự của 8 section cấp cao nhất nên `CLAUDE.md` được sinh ra không còn drift giữa các project, trong khi nội dung mỗi section vẫn thích ứng với từng project. Parser `.env` mới của stack-detector (`lib/env-parser.js`) cung cấp `stack.envInfo` cho prompt để các hàng port/host/API target khớp với giá trị project thực sự khai báo thay vì framework default.
-
-**Pass 4** scaffold L4 Memory layer: các file kiến thức team bền vững (decision-log, failure-patterns, compaction policy, auto-rule-update) cộng với rules `60.memory/` chỉ dẫn các session tương lai khi nào và cách đọc/ghi các file đó. Memory layer là thứ giúp Claude Code tích lũy bài học qua các session thay vì phải khám phá lại mỗi lần. Khi `--lang` khác tiếng Anh, nội dung fallback tĩnh được dịch qua Claude trước khi ghi. v2.1.0 thêm gap-fill cho `skills/00.shared/MANIFEST.md` phòng trường hợp Pass 3c bỏ sót.
+Quy tắc phát hiện và những gì mỗi scanner trích xuất xem tại [docs/vi/stacks.md](docs/vi/stacks.md).
 
 ---
 
-## Cấu Trúc File Được Tạo
-
-```
-your-project/
-│
-├── CLAUDE.md                          ← Entry point của Claude Code (cấu trúc 8-phần deterministic, v2.2.0)
-│
-├── .claude/
-│   └── rules/                         ← Rules kích hoạt theo glob
-│       ├── 00.core/
-│       ├── 10.backend/
-│       ├── 20.frontend/
-│       ├── 30.security-db/
-│       ├── 40.infra/
-│       ├── 50.sync/                   ← Rule nhắc sync
-│       └── 60.memory/                 ← Rule scope on-demand của L4 memory (v2.0.0)
-│
-├── claudeos-core/                     ← Thư mục output chính
-│   ├── generated/                     ← JSON phân tích + prompt động + Pass markers (nên gitignore)
-│   │   ├── project-analysis.json      ← Thông tin stack (multi-stack aware)
-│   │   ├── domain-groups.json         ← Groups với type: backend/frontend
-│   │   ├── pass1-backend-prompt.md    ← Prompt phân tích backend
-│   │   ├── pass1-frontend-prompt.md   ← Prompt phân tích frontend (nếu phát hiện)
-│   │   ├── pass2-prompt.md            ← Prompt merge
-│   │   ├── pass2-merged.json          ← Output Pass 2 (chỉ Pass 3a tiêu thụ)
-│   │   ├── pass3-context.json         ← Slim summary (< 5 KB) cho Pass 3 (v2.1.0)
-│   │   ├── pass3-prompt.md            ← Template prompt Pass 3 (block Phase 1 được thêm trước)
-│   │   ├── pass3a-facts.md            ← Fact sheet được ghi bởi Pass 3a, đọc bởi 3b/3c/3d (v2.1.0)
-│   │   ├── pass4-prompt.md            ← Prompt memory scaffolding (v2.0.0)
-│   │   ├── pass3-complete.json        ← Marker hoàn thành Pass 3 (split mode: bao gồm groupsCompleted, v2.1.0)
-│   │   ├── pass4-memory.json          ← Marker hoàn thành Pass 4 (bỏ qua khi resume)
-│   │   ├── rule-manifest.json         ← Index file cho công cụ xác minh
-│   │   ├── sync-map.json              ← Mapping Plan ↔ disk (rỗng ở v2.1.0; giữ lại để tương thích sync-checker)
-│   │   ├── stale-report.json          ← Kết quả xác minh tổng hợp
-│   │   ├── .i18n-cache-<lang>.json    ← Cache bản dịch (`--lang` khác tiếng Anh)
-│   │   └── .staged-rules/             ← Thư mục staging tạm cho ghi `.claude/rules/` (tự động di chuyển + dọn)
-│   ├── standard/                      ← Coding standards (15-19 file + theo domain ở 60.domains/)
-│   │   ├── 00.core/                   ← Tổng quan, kiến trúc, naming
-│   │   ├── 10.backend-api/            ← API pattern (theo stack)
-│   │   ├── 20.frontend-ui/            ← Frontend pattern (nếu phát hiện)
-│   │   ├── 30.security-db/            ← Security, DB schema, utilities
-│   │   ├── 40.infra/                  ← Config, logging, CI/CD
-│   │   ├── 50.verification/           ← Build verification, testing
-│   │   ├── 60.domains/                ← Standard theo domain (ghi bởi Pass 3b-N, v2.1.0)
-│   │   └── 90.optional/               ← Convention tùy chọn (mở rộng theo stack)
-│   ├── skills/                        ← Skills scaffold CRUD/page
-│   │   └── 00.shared/MANIFEST.md      ← Single source of truth cho skill đã đăng ký
-│   ├── guide/                         ← Onboarding, FAQ, troubleshooting (9 file)
-│   ├── database/                      ← DB schema, hướng dẫn migration
-│   ├── mcp-guide/                     ← Hướng dẫn tích hợp MCP server
-│   └── memory/                        ← L4: kiến thức team (4 file) — commit các file này
-│       ├── decision-log.md            ← Lý do "tại sao" đằng sau quyết định thiết kế
-│       ├── failure-patterns.md        ← Lỗi lặp lại & cách fix (tự chấm điểm — `npx claudeos-core memory score`)
-│       ├── compaction.md              ← Chiến lược compaction 4 giai đoạn (chạy `npx claudeos-core memory compact`)
-│       └── auto-rule-update.md        ← Đề xuất cải tiến rule (`npx claudeos-core memory propose-rules`)
-│
-└── claudeos-core-tools/               ← Toolkit này (không sửa)
-```
-
-Mọi file standard đều bao gồm ví dụ đúng ✅, ví dụ sai ❌, và bảng tóm tắt rule — tất cả đều được trích xuất từ pattern code thực tế của bạn, không phải template chung chung.
-
-> **Lưu ý v2.1.0:** `claudeos-core/plan/` không còn được tạo nữa. Master plan là backup nội bộ mà Claude Code không tiêu thụ lúc runtime, và việc tổng hợp chúng trong Pass 3 là nguyên nhân chính gây tràn output. Dùng `git` để backup/restore thay thế. Các dự án upgrade từ v2.0.x có thể xóa an toàn thư mục `claudeos-core/plan/` hiện có.
+## Workflow hằng ngày
 
-### Đề xuất gitignore
+Ba lệnh phủ ~95% nhu cầu sử dụng:
 
-**Nên commit** (kiến thức team — có mục đích chia sẻ):
-- `CLAUDE.md` — entry point của Claude Code
-- `.claude/rules/**` — rules tự động load
-- `claudeos-core/standard/**`, `skills/**`, `guide/**`, `database/**`, `mcp-guide/**`, `plan/**` — tài liệu được tạo (lưu ý: `plan/**` không còn được tạo ở v2.1.0)
-- `claudeos-core/memory/**` — lịch sử quyết định, failure pattern, đề xuất rule
+```bash
+# Lần đầu trên một dự án
+npx claudeos-core init
 
-**KHÔNG commit** (build artifact có thể tạo lại):
+# Sau khi bạn chỉnh thủ công standards hoặc rules
+npx claudeos-core lint
 
-```gitignore
-# ClaudeOS-Core — phân tích được tạo & cache dịch
-claudeos-core/generated/
+# Health check (chạy trước khi commit, hoặc trong CI)
+npx claudeos-core health
 ```
 
-Thư mục `generated/` chứa JSON phân tích (`pass1-*.json`, `pass2-merged.json`), prompts (`pass1/2/3/4-prompt.md`), Pass completion marker (`pass3-complete.json`, `pass4-memory.json`), translation cache (`.i18n-cache-<lang>.json`), và thư mục staging tạm (`.staged-rules/`) — tất cả có thể xây lại bằng cách chạy lại `npx claudeos-core init`.
-
----
-
-## Tự Động Mở Rộng Theo Kích Thước Dự Án
-
-Split mode của Pass 3 mở rộng số stage theo số domain. Việc chia batch kích hoạt ở 16 domain để giữ output mỗi stage dưới ~50 file, là khoảng an toàn thực nghiệm cho `claude -p` trước khi tràn output do tích lũy.
-
-| Kích thước | Domain | Số stage Pass 3 | Tổng `claude -p` | Thời gian ước tính |
-|---|---|---|---|---|
-| Nhỏ | 1–4 | 4 (`3a`, `3b-core`, `3c-core`, `3d-aux`) | 7 (Pass 1 + 2 + 4 stage Pass 3 + Pass 4) | ~10–15 phút |
-| Vừa | 5–15 | 4 | 8–9 | ~25–45 phút |
-| Lớn | 16–30 | **8** (3b, 3c mỗi cái chia thành 2 batch) | 11–12 | **~60–105 phút** |
-| Rất lớn | 31–45 | 10 | 13–14 | ~100–150 phút |
-| Siêu lớn | 46–60 | 12 | 15–16 | ~150–200 phút |
-| Cực lớn | 61+ | 14+ | 17+ | 200 phút+ |
-
-Công thức số stage (khi chia batch): `1 (3a) + 1 (3b-core) + N (3b-1..N) + 1 (3c-core) + N (3c-1..N) + 1 (3d-aux) = 2N + 4`, với `N = ceil(totalDomains / 15)`.
-
-Pass 4 (memory scaffolding) thêm khoảng ~30 giây đến 5 phút lên trên tùy thuộc vào việc chạy tạo qua Claude hay fallback tĩnh. Với dự án multi-stack (ví dụ Java + React), domain backend và frontend được đếm cộng lại. Dự án 6 backend + 4 frontend = 10 tổng = tier Vừa.
-
----
-
-## Công Cụ Xác Minh
-
-ClaudeOS-Core bao gồm 5 công cụ xác minh built-in chạy tự động sau khi tạo:
+Hai lệnh nữa cho bảo trì memory layer:
 
 ```bash
-# Chạy tất cả kiểm tra cùng lúc (khuyến nghị)
-npx claudeos-core health
-
-# Lệnh riêng lẻ
-npx claudeos-core validate     # So sánh Plan ↔ disk
-npx claudeos-core refresh      # Disk → Plan sync
-npx claudeos-core restore      # Plan → Disk restore
+# Compact log failure-patterns (chạy định kỳ)
+npx claudeos-core memory compact
 
-# Hoặc dùng node trực tiếp (cho người dùng git clone)
-node claudeos-core-tools/health-checker/index.js
-node claudeos-core-tools/manifest-generator/index.js
-node claudeos-core-tools/plan-validator/index.js --check
-node claudeos-core-tools/sync-checker/index.js
+# Đề xuất các pattern lỗi thường gặp thành rule mới
+npx claudeos-core memory propose-rules
 ```
 
-| Công cụ | Chức năng |
-|---|---|
-| **manifest-generator** | Tạo JSON metadata (`rule-manifest.json`, `sync-map.json`, khởi tạo `stale-report.json`); index 7 thư mục bao gồm `memory/` (`totalMemory` trong summary). v2.1.0: `plan-manifest.json` không còn được tạo vì master plan đã bị loại bỏ. |
-| **plan-validator** | Xác minh block `<file>` master plan với disk cho các dự án vẫn còn `claudeos-core/plan/` (trường hợp upgrade legacy). v2.1.0: bỏ qua tạo `plan-sync-status.json` khi `plan/` vắng mặt hoặc rỗng — `stale-report.json` vẫn ghi một no-op pass. |
-| **sync-checker** | Phát hiện file chưa đăng ký (trên disk nhưng không có trong plan) và entry orphan — bao phủ 7 thư mục (thêm `memory/` ở v2.0.0). Thoát sạch khi `sync-map.json` không có mapping nào (trạng thái mặc định của v2.1.0). |
-| **content-validator** | Kiểm tra chất lượng 9 mục — file rỗng, thiếu ví dụ ✅/❌, mục bắt buộc, cộng với toàn vẹn scaffold L4 memory (ngày heading decision-log, trường bắt buộc failure-pattern, parse nhận biết fence) |
-| **pass-json-validator** | Xác minh cấu trúc JSON Pass 1–4 cộng với marker hoàn thành `pass3-complete.json` (shape split-mode, v2.1.0) và `pass4-memory.json` |
+Tùy chọn đầy đủ của từng lệnh xem tại [docs/vi/commands.md](docs/vi/commands.md).
 
 ---
 
-## Cách Claude Code Dùng Tài Liệu Của Bạn
-
-ClaudeOS-Core tạo tài liệu mà Claude Code thực sự đọc — đây là cách:
-
-### Cái Claude Code đọc tự động
-
-| File | Khi nào | Đảm bảo |
-|---|---|---|
-| `CLAUDE.md` | Mỗi lần bắt đầu hội thoại | Luôn luôn |
-| `.claude/rules/00.core/*` | Khi sửa bất kỳ file nào (`paths: ["**/*"]`) | Luôn luôn |
-| `.claude/rules/10.backend/*` | Khi sửa bất kỳ file nào (`paths: ["**/*"]`) | Luôn luôn |
-| `.claude/rules/20.frontend/*` | Khi sửa bất kỳ file frontend nào (scope tới đường dẫn component/page/style) | Có điều kiện |
-| `.claude/rules/30.security-db/*` | Khi sửa bất kỳ file nào (`paths: ["**/*"]`) | Luôn luôn |
-| `.claude/rules/40.infra/*` | Chỉ khi sửa file config/infra (đường dẫn có scope) | Có điều kiện |
-| `.claude/rules/50.sync/*` | Chỉ khi sửa file claudeos-core (đường dẫn có scope) | Có điều kiện |
-| `.claude/rules/60.memory/*` | Khi sửa `claudeos-core/memory/*` (scope tới đường dẫn memory) — chỉ dẫn **cách** đọc/ghi memory layer on-demand | Có điều kiện (v2.0.0) |
+## Điều gì làm công cụ này khác biệt
 
-### Cái Claude Code đọc theo yêu cầu qua rule references
+Hầu hết công cụ sinh tài liệu Claude Code đều sinh từ một mô tả (bạn nói cho công cụ, công cụ nói cho Claude). ClaudeOS-Core sinh từ chính mã nguồn của bạn (công cụ đọc, công cụ nói cho Claude phần nào đã được xác nhận, Claude chỉ viết những gì đã được xác nhận).
 
-Mỗi file rule link tới standard tương ứng qua mục `## Reference`. Claude chỉ đọc standard liên quan cho task hiện tại:
+Ba hệ quả cụ thể:
 
-- `claudeos-core/standard/**` — coding pattern, ví dụ ✅/❌, convention đặt tên
-- `claudeos-core/database/**` — DB schema (cho query, mapper, migration)
-- `claudeos-core/memory/**` (v2.0.0) — L4 team knowledge layer; **không** auto-load (sẽ quá nhiễu ở mỗi hội thoại). Thay vào đó, các rule `60.memory/*` chỉ dẫn Claude *khi nào* Read các file này: ở đầu session (lướt qua `decision-log.md` gần đây + `failure-patterns.md` importance cao), và append theo yêu cầu khi ra quyết định hoặc gặp lỗi lặp lại.
+1. **Phát hiện stack có tính deterministic.** Cùng dự án + cùng code = cùng đầu ra. Không có chuyện "lần này Claude đoán khác."
+2. **Không bịa ra đường dẫn.** Prompt của Pass 3 liệt kê tường minh mọi đường dẫn nguồn được phép; Claude không thể trích các đường dẫn không tồn tại.
+3. **Hiểu đa-stack.** Domain backend và frontend dùng prompt phân tích khác nhau trong cùng một lần chạy.
 
-`00.standard-reference.md` đóng vai trò như danh bạ của tất cả file standard để phát hiện những standard không có rule tương ứng.
-
-### Cái Claude Code KHÔNG đọc (tiết kiệm context)
-
-Các folder này được loại trừ rõ ràng qua mục `DO NOT Read` trong rule standard-reference:
-
-| Folder | Lý do loại trừ |
-|---|---|
-| `claudeos-core/plan/` | Master Plan backup từ các dự án legacy (v2.0.x và trước đó). Không tạo ở v2.1.0. Nếu có mặt, Claude Code sẽ không tự động load — chỉ đọc theo yêu cầu. |
-| `claudeos-core/generated/` | JSON metadata build, prompt, Pass marker, translation cache, `.staged-rules/`. Không dùng cho coding. |
-| `claudeos-core/guide/` | Hướng dẫn onboarding cho con người. |
-| `claudeos-core/mcp-guide/` | Tài liệu MCP server. Không dùng cho coding. |
-| `claudeos-core/memory/` (auto-load) | **Auto-load bị tắt** có chủ đích — sẽ làm phồng context ở mỗi hội thoại. Đọc theo yêu cầu qua rule `60.memory/*` thay thế (ví dụ: scan `failure-patterns.md` lúc bắt đầu session). Luôn commit các file này. |
+So sánh phạm vi side-by-side với các công cụ khác xem [docs/vi/comparison.md](docs/vi/comparison.md). So sánh là về **mỗi công cụ làm gì**, không phải **cái nào tốt hơn** — phần lớn là bổ trợ nhau.
 
 ---
 
-## Quy Trình Hằng Ngày
+## Xác minh (sau khi sinh)
 
-### Sau Khi Cài Đặt
+Sau khi Claude viết doc, code sẽ xác minh chúng. Năm validator độc lập:
 
-```
-# Chỉ dùng Claude Code như bình thường — nó tham chiếu standard của bạn tự động:
-"Tạo CRUD cho domain order"
-"Thêm API cập nhật profile người dùng"
-"Refactor code này khớp với pattern dự án"
-```
+| Validator | Kiểm tra gì | Chạy bởi |
+|---|---|---|
+| `claude-md-validator` | Bất biến cấu trúc của CLAUDE.md (8 sections, language-invariant) | `claudeos-core lint` |
+| `content-validator` | Đường dẫn nêu trong tài liệu thật sự tồn tại; manifest nhất quán | `health` (advisory) |
+| `pass-json-validator` | Đầu ra Pass 1 / 2 / 3 / 4 là JSON đúng cú pháp | `health` (warn) |
+| `plan-validator` | Plan đã lưu khớp với đĩa | `health` (fail-on-error) |
+| `sync-checker` | Tệp trên đĩa khớp với đăng ký trong `sync-map.json` (phát hiện orphaned/unregistered) | `health` (fail-on-error) |
 
-### Sau Khi Sửa Standard Thủ Công
+Một `health-checker` điều phối bốn validator runtime với mức độ ba bậc (fail / warn / advisory) và thoát với exit code phù hợp cho CI. `claude-md-validator` chạy riêng qua lệnh `lint` vì lệch cấu trúc là tín hiệu cần re-init, không phải warning nhẹ. Có thể chạy bất cứ lúc nào:
 
 ```bash
-# Sau khi sửa file standard hoặc rules:
-npx claudeos-core refresh
-
-# Xác minh mọi thứ nhất quán
 npx claudeos-core health
 ```
 
-### Khi Docs Bị Hỏng
-
-```bash
-# Khuyến nghị v2.1.0: dùng git để khôi phục (vì master plan không còn
-# được tạo nữa). Commit tài liệu được tạo thường xuyên để có thể rollback
-# từng file cụ thể mà không cần tạo lại:
-git checkout HEAD -- .claude/rules/ claudeos-core/
-
-# Legacy (dự án v2.0.x vẫn còn claudeos-core/plan/):
-npx claudeos-core restore
-```
-
-### Bảo Trì Memory Layer (v2.0.0)
-
-L4 Memory layer (`claudeos-core/memory/`) tích lũy kiến thức team qua các session. Ba CLI subcommand giữ nó khỏe mạnh:
-
-```bash
-# Compact: áp dụng chính sách compaction 4 giai đoạn (chạy định kỳ — ví dụ hàng tháng)
-npx claudeos-core memory compact
-#   Stage 1: tóm tắt các entry cũ (>30 ngày, body → một dòng)
-#   Stage 2: merge heading trùng (tổng frequency, giữ fix mới nhất)
-#   Stage 3: bỏ importance thấp + cũ (importance <3 VÀ lastSeen >60 ngày)
-#   Stage 4: áp dụng giới hạn 400 dòng mỗi file (bỏ importance thấp cũ nhất trước)
-
-# Score: xếp hạng lại các entry trong failure-patterns.md theo importance
-npx claudeos-core memory score
-#   importance = round(frequency × 1.5 + recency × 5), giới hạn 10
-#   Chạy sau khi append vài failure pattern mới
-
-# Propose-rules: nổi bật các candidate rule addition từ failure lặp lại
-npx claudeos-core memory propose-rules
-#   Đọc các entry failure-patterns.md với frequency ≥ 3
-#   Tính confidence (sigmoid trên weighted evidence × anchor multiplier)
-#   Ghi proposal vào memory/auto-rule-update.md (KHÔNG tự động áp dụng)
-#   Confidence ≥ 0.70 đáng xem xét nghiêm túc; nếu accept → sửa rule + log quyết định
-
-# v2.1.0: `memory --help` giờ route tới help subcommand (trước đây hiển thị top-level)
-npx claudeos-core memory --help
-```
-
-> **Fix v2.1.0:** `memory score` không còn để lại dòng `importance` trùng lặp sau lần chạy đầu (trước đây dòng được tự chấm điểm được thêm ở trên trong khi dòng nguyên bản bị bỏ lại bên dưới). Marker summary Stage 1 của `memory compact` giờ là markdown list item đúng định dạng (`- _Summarized on ..._`) nên render sạch và được parse lại đúng ở các lần compact sau.
-
-Khi nào ghi vào memory (Claude làm theo yêu cầu, nhưng bạn cũng có thể sửa thủ công):
-- **`decision-log.md`** — append entry mới bất cứ khi nào bạn chọn giữa các pattern cạnh tranh, chọn thư viện, định nghĩa convention team, hoặc quyết định KHÔNG làm gì đó. Chỉ append; không bao giờ sửa entry lịch sử.
-- **`failure-patterns.md`** — append vào **lần xuất hiện thứ hai** của lỗi lặp lại hoặc nguyên nhân không hiển nhiên. Lỗi lần đầu không cần entry.
-- `compaction.md` và `auto-rule-update.md` — được tạo/quản lý bởi các CLI subcommand trên; không sửa bằng tay.
-
-### Tích Hợp CI/CD
-
-```yaml
-# Ví dụ GitHub Actions
-- run: npx claudeos-core validate
-# Exit code 1 chặn PR
-
-# Tùy chọn: housekeeping memory hàng tháng (workflow cron riêng)
-- run: npx claudeos-core memory compact
-- run: npx claudeos-core memory score
-```
+Chi tiết kiểm tra của từng validator xem [docs/vi/verification.md](docs/vi/verification.md).
 
 ---
 
-## Khác Biệt Ra Sao?
-
-### So với Các Công Cụ Claude Code Khác
-
-| | ClaudeOS-Core | Everything Claude Code (50K+ ⭐) | Harness | specs-generator | Claude `/init` |
-|---|---|---|---|---|---|
-| **Cách tiếp cận** | Code phân tích trước, rồi LLM tạo | Preset config dựng sẵn | LLM thiết kế agent team | LLM tạo spec doc | LLM viết CLAUDE.md |
-| **Đọc source code** | ✅ Phân tích tĩnh deterministic | ❌ | ❌ | ❌ (LLM đọc) | ❌ (LLM đọc) |
-| **Phát hiện stack** | Code xác nhận (ORM, DB, build tool, pkg manager) | N/A (stack-agnostic) | LLM đoán | LLM đoán | LLM đoán |
-| **Phát hiện domain** | Code xác nhận (Java 5 pattern, Kotlin CQRS, Next.js FSD) | N/A | LLM đoán | N/A | N/A |
-| **Cùng dự án → cùng kết quả** | ✅ Phân tích deterministic | ✅ (file tĩnh) | ❌ (LLM thay đổi) | ❌ (LLM thay đổi) | ❌ (LLM thay đổi) |
-| **Xử lý dự án lớn** | Chia domain group (4 domain / 40 file mỗi group) | N/A | Không chia | Không chia | Giới hạn context window |
-| **Output** | CLAUDE.md + Rules + Standards + Skills + Guides + Plans (40-50+ file) | Agents + Skills + Commands + Hooks | Agents + Skills | 6 spec document | CLAUDE.md (1 file) |
-| **Vị trí output** | `.claude/rules/` (tự load bởi Claude Code) | `.claude/` đủ loại | `.claude/agents/` + `.claude/skills/` | `.claude/steering/` + `specs/` | `CLAUDE.md` |
-| **Xác minh sau khi tạo** | ✅ 5 validator tự động | ❌ | ❌ | ❌ | ❌ |
-| **Output đa ngôn ngữ** | ✅ 10 ngôn ngữ | ❌ | ❌ | ❌ | ❌ |
-| **Multi-stack** | ✅ Backend + Frontend đồng thời | ❌ Stack-agnostic | ❌ | ❌ | Một phần |
-| **Memory layer bền vững** | ✅ L4 — decision log + failure pattern + đề xuất rule chấm điểm tự động (v2.0.0) | ❌ | ❌ | ❌ | ❌ |
-| **Điều phối agent** | ❌ | ✅ 28 agent | ✅ 6 pattern | ❌ | ❌ |
+## Memory Layer (tùy chọn, dành cho dự án dài hạn)
 
-### Khác biệt chính trong một câu
+Sau v2.0, ClaudeOS-Core ghi một thư mục `claudeos-core/memory/` chứa bốn tệp:
 
-**Các công cụ khác cho Claude "instructions tốt nói chung". ClaudeOS-Core cho Claude "instructions trích xuất từ code thực tế của bạn".**
+- `decision-log.md` — append-only "vì sao chọn X thay vì Y"
+- `failure-patterns.md` — lỗi tái diễn kèm điểm frequency/importance
+- `compaction.md` — cách memory được tự động compact theo thời gian
+- `auto-rule-update.md` — pattern cần được biến thành rule mới
 
-Đó là lý do Claude Code ngừng tạo code JPA trong dự án MyBatis,
-ngừng dùng `success()` khi codebase của bạn dùng `ok()`,
-và ngừng tạo thư mục `user/controller/` khi dự án của bạn dùng `controller/user/`.
+Bạn có thể chạy `npx claudeos-core memory propose-rules` để yêu cầu Claude xem xét các pattern lỗi gần đây và đề xuất rule mới.
 
-### Bổ sung, không cạnh tranh
-
-ClaudeOS-Core tập trung vào **rule và standard đặc thù dự án**.
-Các công cụ khác tập trung vào **điều phối agent và workflow**.
-
-Bạn có thể dùng ClaudeOS-Core để tạo rule cho dự án, rồi dùng ECC hoặc Harness bên trên cho agent team và tự động hóa workflow. Chúng giải quyết các vấn đề khác nhau.
+Mô hình memory và vòng đời xem [docs/vi/memory-layer.md](docs/vi/memory-layer.md).
 
 ---
 
 ## FAQ
 
-**Q: Nó có sửa source code của tôi không?**
-Không. Nó chỉ tạo `CLAUDE.md`, `.claude/rules/`, và `claudeos-core/`. Code hiện có của bạn không bao giờ bị sửa.
-
-**Q: Chi phí là bao nhiêu?**
-Nó gọi `claude -p` vài lần qua 4 pass. Ở split mode v2.1.0, chỉ riêng Pass 3 đã mở rộng thành 4–14+ stage tùy theo kích thước dự án (xem [Tự Động Mở Rộng](#tự-động-mở-rộng-theo-kích-thước-dự-án)). Một dự án nhỏ điển hình (1–15 domain) dùng tổng cộng 8–9 lời gọi `claude -p`; dự án 18 domain dùng 11; dự án 60 domain dùng 15–17. Mỗi stage chạy với context window mới — chi phí token mỗi lời gọi thực ra thấp hơn Pass 3 lời-gọi-đơn, vì không stage nào phải giữ toàn bộ cây file trong một context. Khi `--lang` khác tiếng Anh, đường fallback tĩnh có thể gọi thêm vài `claude -p` để dịch; kết quả được cache trong `claudeos-core/generated/.i18n-cache-<lang>.json` nên các lần chạy sau dùng lại. Vẫn nằm trong mức sử dụng Claude Code bình thường.
-
-**Q: Pass 3 split mode là gì và tại sao được thêm ở v2.1.0?**
-Trước v2.1.0, Pass 3 thực hiện một lời gọi `claude -p` đơn phải phát ra toàn bộ cây file được tạo (`CLAUDE.md`, standards, rules, skills, guides — thường 30–60 file) trong một response. Điều này hoạt động trên dự án nhỏ nhưng luôn gặp lỗi `Prompt is too long` do tích lũy output ở ~5 domain. Lỗi không thể dự đoán từ kích thước input — nó phụ thuộc vào mức độ dài dòng của mỗi file được tạo, và có thể ập đến cùng một dự án một cách không ổn định. Split mode né vấn đề này về cấu trúc: Pass 3 được chia thành các stage tuần tự (`3a` → `3b-core` → `3b-N` → `3c-core` → `3c-N` → `3d-aux`), mỗi cái là một lời gọi `claude -p` riêng với context window mới. Tính nhất quán xuyên stage được bảo tồn bởi `pass3a-facts.md`, fact sheet đã chắt lọc 5–10 KB mà mọi stage sau tham chiếu thay vì đọc lại `pass2-merged.json`. Marker `pass3-complete.json` mang mảng `groupsCompleted` để crash trong `3c-2` resume từ `3c-2` (không phải từ `3a`), tránh chi phí token gấp đôi.
-**Q: Tôi có nên commit các file được tạo vào Git không?**
-Có, khuyến nghị. Team của bạn có thể chia sẻ cùng standard Claude Code. Hãy xem xét thêm `claudeos-core/generated/` vào `.gitignore` (JSON phân tích có thể tạo lại).
-
-**Q: Còn dự án mixed-stack (ví dụ Java backend + React frontend)?**
-Được hỗ trợ hoàn toàn. ClaudeOS-Core tự phát hiện cả hai stack, gắn tag domain là `backend` hoặc `frontend`, và dùng prompt phân tích theo stack cho mỗi cái. Pass 2 merge mọi thứ, và Pass 3 tạo cả standard backend và frontend qua các split stage — domain backend rơi vào một số batch 3b/3c, domain frontend vào các batch khác, tất cả đều tham chiếu cùng `pass3a-facts.md` để có tính nhất quán.
-
-**Q: Nó có hoạt động với monorepo Turborepo / pnpm workspaces / Lerna không?**
-Có. ClaudeOS-Core phát hiện `turbo.json`, `pnpm-workspace.yaml`, `lerna.json`, hoặc `package.json#workspaces` và tự động quét file `package.json` của sub-package để tìm dependency framework/ORM/DB. Quét domain bao phủ pattern `apps/*/src/` và `packages/*/src/`. Chạy từ root monorepo.
-
-**Q: Chạy lại thì chuyện gì xảy ra?**
-Nếu kết quả Pass 1/2 trước đó tồn tại, một prompt tương tác cho bạn chọn: **Continue** (tiếp tục từ chỗ dừng) hoặc **Fresh** (xóa tất cả và bắt đầu lại). Dùng `--force` để bỏ qua prompt và luôn bắt đầu mới. Ở split mode v2.1.0, resume Pass 3 hoạt động ở mức độ stage — nếu lần chạy crash trong `3c-2`, `init` tiếp theo resume từ `3c-2` thay vì bắt đầu lại từ `3a` (sẽ nhân đôi chi phí token). Marker `pass3-complete.json` ghi `mode: "split"` cộng với mảng `groupsCompleted` để điều khiển logic này.
-
-**Q: NestJS có template riêng hay dùng của Express?**
-NestJS dùng template `node-nestjs` chuyên dụng với các danh mục phân tích đặc thù NestJS: decorator `@Module`, `@Injectable`, `@Controller`, Guards, Pipes, Interceptors, DI container, pattern CQRS, và `Test.createTestingModule`. Dự án Express dùng template `node-express` riêng biệt.
+**H: Tôi có cần Claude API key không?**
+Đ: Không. ClaudeOS-Core dùng cài đặt Claude Code sẵn có của bạn — nó truyền prompt đến `claude -p` trên máy bạn. Không cần tài khoản phụ.
 
-**Q: Còn dự án Vue / Nuxt?**
-Vue/Nuxt dùng template `vue-nuxt` chuyên dụng bao phủ Composition API, `<script setup>`, defineProps/defineEmits, Pinia store, `useFetch`/`useAsyncData`, Nitro server route, và `@nuxt/test-utils`. Dự án Next.js/React dùng template `node-nextjs`.
+**H: Lệnh này có ghi đè CLAUDE.md hoặc `.claude/rules/` đang có không?**
+Đ: Lần chạy đầu trên dự án mới: tạo mới. Chạy lại không có `--force` thì giữ nguyên chỉnh sửa của bạn — marker từ lần chạy trước được phát hiện và pass đó bị bỏ qua. Chạy lại với `--force` thì xóa và sinh lại tất cả (các chỉnh sửa của bạn bị mất — đó chính là ý nghĩa của `--force`). Xem [docs/vi/safety.md](docs/vi/safety.md).
 
-**Q: Nó có hỗ trợ Kotlin không?**
-Có. ClaudeOS-Core tự phát hiện Kotlin từ `build.gradle.kts` hoặc kotlin plugin trong `build.gradle`. Nó dùng template `kotlin-spring` chuyên dụng với phân tích đặc thù Kotlin (data class, sealed class, coroutine, extension function, MockK, v.v.).
+**H: Stack của tôi không được hỗ trợ. Tôi có thể thêm không?**
+Đ: Có. Stack mới cần ~3 prompt template + một domain scanner. Xem [CONTRIBUTING.md](CONTRIBUTING.md) để có hướng dẫn 8 bước.
 
-**Q: Còn kiến trúc CQRS / BFF?**
-Được hỗ trợ hoàn toàn cho dự án Kotlin multi-module. ClaudeOS-Core đọc `settings.gradle.kts`, phát hiện kiểu module (command, query, bff, integration) từ tên module, và nhóm cùng domain qua các module Command/Query. Các standard được tạo bao gồm rule riêng cho command controller vs query controller, pattern BFF/Feign, và convention giao tiếp liên module.
+**H: Làm sao sinh doc bằng tiếng Việt (hoặc ngôn ngữ khác)?**
+Đ: `npx claudeos-core init --lang vi`. Hỗ trợ 10 ngôn ngữ: en, ko, ja, zh-CN, es, vi, hi, ru, fr, de.
 
-**Q: Còn Gradle multi-module monorepo?**
-ClaudeOS-Core quét tất cả submodule (`**/src/main/kotlin/**/*.kt`) bất kể độ sâu nesting. Kiểu module được suy ra từ convention đặt tên (ví dụ `reservation-command-server` → domain: `reservation`, type: `command`). Các thư viện shared (`shared-lib`, `integration-lib`) cũng được phát hiện.
+**H: Có chạy với monorepo không?**
+Đ: Có — Turborepo (`turbo.json`), pnpm workspaces (`pnpm-workspace.yaml`), Lerna (`lerna.json`) và npm/yarn workspaces (`package.json#workspaces`) được stack-detector phát hiện. Mỗi app được phân tích riêng. Các layout monorepo khác (ví dụ NX) không được phát hiện đặc biệt, nhưng các pattern chung `apps/*/` và `packages/*/` vẫn được scanner theo từng stack nhặt được.
 
-**Q: L4 Memory layer là gì (v2.0.0)? Tôi có nên commit `claudeos-core/memory/` không?**
-Có — **luôn commit** `claudeos-core/memory/`. Đó là kiến thức team bền vững: `decision-log.md` ghi lại *lý do* đằng sau các lựa chọn kiến trúc (chỉ append), `failure-patterns.md` đăng ký các lỗi lặp lại với importance score để session tương lai tránh, `compaction.md` định nghĩa chính sách compaction 4 giai đoạn, và `auto-rule-update.md` thu thập các đề xuất cải tiến rule do máy tạo. Khác với rule (tự load theo path), file memory là **on-demand** — Claude chỉ đọc khi rule `60.memory/*` hướng dẫn (ví dụ: scan failure importance cao lúc bắt đầu session). Điều này giữ chi phí context thấp trong khi bảo toàn kiến thức dài hạn.
+**H: Nếu Claude Code sinh ra rule mà tôi không đồng ý thì sao?**
+Đ: Sửa trực tiếp. Sau đó chạy `npx claudeos-core lint` để kiểm tra CLAUDE.md vẫn đúng cấu trúc. Các chỉnh sửa của bạn được giữ qua các lần `init` sau (không có `--force`) — cơ chế resume bỏ qua các pass đã có marker.
 
-**Q: Nếu Pass 4 lỗi thì sao?**
-Pipeline tự động (`npx claudeos-core init`) có static fallback: nếu `claude -p` lỗi hoặc thiếu `pass4-prompt.md`, nó scaffold memory layer trực tiếp qua `lib/memory-scaffold.js`. Khi `--lang` khác tiếng Anh, static fallback **phải** dịch qua CLI `claude` — nếu cũng lỗi, lần chạy sẽ abort với `InitError` (không fallback âm thầm về English). Chạy lại khi `claude` đã xác thực, hoặc dùng `--lang en` để bỏ qua dịch. Kết quả dịch được cache trong `claudeos-core/generated/.i18n-cache-<lang>.json` nên lần chạy sau dùng lại.
-
-**Q: `memory compact` / `memory score` / `memory propose-rules` làm gì?**
-Xem mục [Bảo Trì Memory Layer](#bảo-trì-memory-layer-v200) ở trên. Phiên bản ngắn: `compact` chạy chính sách 4 giai đoạn (tóm tắt cũ, merge trùng, bỏ importance thấp cũ, áp dụng giới hạn 400 dòng); `score` xếp hạng lại `failure-patterns.md` theo importance (frequency × recency); `propose-rules` nổi bật candidate rule addition từ failure lặp lại vào `auto-rule-update.md` (không tự động áp dụng — xem và accept/reject thủ công).
-
-**Q: Tại sao `--force` (hoặc chế độ "fresh" resume) xóa `.claude/rules/`?**
-v2.0.0 thêm ba silent-failure guard cho Pass 3 (Guard 3 bao phủ hai biến thể output không đầy đủ: H2 cho `guide/` và H1 cho `standard/skills`). Guard 1 ("partial staged-rules move") và Guard 3 ("incomplete output — missing/empty guide files or missing standard sentinel / empty skills") không phụ thuộc vào rule hiện có, nhưng Guard 2 ("zero rules detected") thì có — nó kích hoạt khi Claude bỏ qua directive `staging-override.md` và thử ghi trực tiếp vào `.claude/` (nơi chính sách sensitive-path của Claude Code chặn). Rule cũ từ lần chạy trước sẽ khiến Guard 2 false-negative — nên `--force`/`fresh` xóa `.claude/rules/` để đảm bảo phát hiện sạch. **Sửa rule thủ công sẽ bị mất** dưới `--force`/`fresh`; hãy backup trước nếu cần. (Lưu ý v2.1.0: Guard 3 H1 không còn kiểm tra `plan/` vì master plan không còn được tạo.)
-
-**Q: `claudeos-core/generated/.staged-rules/` là gì và tại sao tồn tại?**
-Chính sách sensitive-path của Claude Code từ chối ghi trực tiếp vào `.claude/` từ subprocess `claude -p` (ngay cả với `--dangerously-skip-permissions`). v2.0.0 đi vòng bằng cách cho prompt Pass 3/4 chuyển hướng mọi ghi `.claude/rules/` vào thư mục staging; orchestrator Node.js (không chịu chính sách đó) sau đó di chuyển cây staged vào `.claude/rules/` sau mỗi pass. Điều này trong suốt với người dùng — thư mục được tự tạo, tự dọn, và tự di chuyển. Nếu lần chạy trước crash giữa chừng di chuyển, lần chạy sau xóa staging dir trước khi thử lại. Ở split mode v2.1.0, stage runner di chuyển staged rules vào `.claude/rules/` sau mỗi stage (không chỉ cuối cùng), nên crash giữa Pass 3 vẫn để lại rule của các stage đã hoàn thành trước đó tại chỗ.
-
-**Q: Tôi có thể chạy Pass 3 thủ công thay vì `npx claudeos-core init` không?**
-Có cho dự án nhỏ (≤5 domain) — hướng dẫn thủ công lời-gọi-đơn ở [Step 6](#step-6-pass-3--tạo-toàn-bộ-tài-liệu-chia-thành-nhiều-stage) vẫn hoạt động. Cho dự án lớn hơn bạn nên dùng `npx claudeos-core init` vì split runner là cái điều phối thực thi từng stage với context mới, xử lý chia batch ở ≥16 domain, ghi shape marker `pass3-complete.json` đúng (`mode: "split"` + `groupsCompleted`), và di chuyển staged rules giữa các stage. Tái tạo điều phối đó bằng tay có thể được nhưng mệt mỏi. Nếu bạn có lý do chạy stage thủ công (ví dụ: debug một stage cụ thể), bạn có thể template `pass3-prompt.md` với directive `STAGE:` phù hợp và đưa cho `claude -p` trực tiếp — nhưng nhớ di chuyển `.staged-rules/` sau mỗi stage và tự cập nhật marker.
-
-**Q: Dự án của tôi là upgrade từ v2.0.x và có thư mục `claudeos-core/plan/` hiện hữu. Tôi phải làm gì?**
-Không cần gì cả — công cụ v2.1.0 bỏ qua `plan/` khi nó vắng mặt hoặc rỗng, và `plan-validator` vẫn xử lý các dự án legacy có thư mục `plan/` đã điền để tương thích ngược. Bạn có thể xóa an toàn `claudeos-core/plan/` nếu không cần master plan backup (git history dù sao cũng là backup tốt hơn). Nếu giữ `plan/`, chạy `npx claudeos-core init` sẽ không cập nhật nó — nội dung mới không được tổng hợp vào master plan ở v2.1.0. Công cụ xác minh xử lý sạch cả hai trường hợp.
+**H: Báo bug ở đâu?**
+Đ: [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Vấn đề bảo mật xem [SECURITY.md](SECURITY.md).
 
 ---
 
-## Cấu Trúc Template
-
-```
-pass-prompts/templates/
-├── common/                  # header/footer dùng chung + pass4 + staging-override + CLAUDE.md scaffold (v2.2.0)
-│   ├── header.md             # Vai trò + chỉ thị định dạng output (tất cả pass)
-│   ├── pass3-footer.md       # Chỉ thị health-check sau Pass 3 + 5 khối guardrail CRITICAL (v2.2.0)
-│   ├── pass3-phase1.md       # Khối "Read Once, Extract Facts" với Rule A-E (v2.1.0)
-│   ├── pass4.md              # Prompt scaffolding memory (v2.0.0)
-│   ├── staging-override.md   # Chuyển hướng write .claude/rules/** sang .staged-rules/** (v2.0.0)
-│   ├── claude-md-scaffold.md # Template CLAUDE.md 8 section tất định (v2.2.0)
-│   └── lang-instructions.json # Chỉ thị output theo ngôn ngữ (10 ngôn ngữ)
-├── java-spring/             # Java / Spring Boot
-├── kotlin-spring/           # Kotlin / Spring Boot (CQRS, BFF, multi-module)
-├── node-express/            # Node.js / Express
-├── node-nestjs/             # Node.js / NestJS (Module, DI, Guard, Pipe, Interceptor)
-├── node-fastify/            # Node.js / Fastify
-├── node-nextjs/             # Next.js / React (App Router, RSC)
-├── node-vite/               # Vite SPA (React, client-side routing, VITE_ env, Vitest)
-├── vue-nuxt/                # Vue / Nuxt (Composition API, Pinia, Nitro)
-├── angular/                 # Angular
-├── python-django/           # Python / Django (DRF)
-├── python-fastapi/          # Python / FastAPI
-└── python-flask/            # Python / Flask (Blueprint, app factory, Jinja2)
-```
-
-`plan-installer` tự phát hiện các stack của bạn, rồi lắp ráp prompt theo kiểu. NestJS, Vue/Nuxt, Vite SPA và Flask mỗi cái dùng template chuyên dụng với danh mục phân tích đặc thù framework (ví dụ: `@Module`/`@Injectable`/Guards cho NestJS; `<script setup>`/Pinia/useFetch cho Vue; client-side routing/`VITE_` env cho Vite; Blueprint/`app.factory`/Flask-SQLAlchemy cho Flask). Cho dự án multi-stack, `pass1-backend-prompt.md` và `pass1-frontend-prompt.md` riêng biệt được tạo, trong khi `pass3-prompt.md` kết hợp mục tiêu tạo của cả hai stack. Ở v2.1.0, template Pass 3 được thêm `common/pass3-phase1.md` (block "Read Once, Extract Facts" với Rules A–E) vào đầu trước khi được cắt theo từng stage split-mode. Pass 4 dùng template chung `common/pass4.md` (memory scaffolding) bất kể stack.
+## Documentation
 
-**Trong v2.2.0**, prompt Pass 3 cũng chèn inline `common/claude-md-scaffold.md` (template CLAUDE.md 8 section tất định) vào giữa khối phase1 và thân stack-specific — điều này cố định cấu trúc section để CLAUDE.md được tạo ra không bị drift giữa các project, trong khi nội dung vẫn thích ứng theo project. Template được viết **English-first**; việc inject ngôn ngữ từ `lang-instructions.json` chỉ thị LLM dịch tiêu đề section và văn xuôi sang ngôn ngữ output đích tại thời điểm emit.
+| Chủ đề | Đọc tại |
+|---|---|
+| Cách pipeline 4-pass hoạt động (sâu hơn diagram) | [docs/vi/architecture.md](docs/vi/architecture.md) |
+| Diagram trực quan (Mermaid) của kiến trúc | [docs/vi/diagrams.md](docs/vi/diagrams.md) |
+| Phát hiện stack — mỗi scanner tìm gì | [docs/vi/stacks.md](docs/vi/stacks.md) |
+| Memory layer — decision log và failure pattern | [docs/vi/memory-layer.md](docs/vi/memory-layer.md) |
+| Chi tiết cả 5 validator | [docs/vi/verification.md](docs/vi/verification.md) |
+| Mọi lệnh CLI và tùy chọn | [docs/vi/commands.md](docs/vi/commands.md) |
+| Cài thủ công (không dùng `npx`) | [docs/vi/manual-installation.md](docs/vi/manual-installation.md) |
+| Override scanner — `.claudeos-scan.json` | [docs/vi/advanced-config.md](docs/vi/advanced-config.md) |
+| An toàn: cái gì được giữ khi re-init | [docs/vi/safety.md](docs/vi/safety.md) |
+| So sánh với các công cụ tương tự (về phạm vi, không phải chất lượng) | [docs/vi/comparison.md](docs/vi/comparison.md) |
+| Lỗi và cách phục hồi | [docs/vi/troubleshooting.md](docs/vi/troubleshooting.md) |
 
 ---
 
-## Hỗ Trợ Monorepo
-
-ClaudeOS-Core tự động phát hiện setup monorepo JS/TS và quét sub-package tìm dependency.
-
-**Các monorepo marker được hỗ trợ** (tự phát hiện):
-- `turbo.json` (Turborepo)
-- `pnpm-workspace.yaml` (pnpm workspaces)
-- `lerna.json` (Lerna)
-- `package.json#workspaces` (npm/yarn workspaces)
-
-**Chạy từ root monorepo** — ClaudeOS-Core đọc `apps/*/package.json` và `packages/*/package.json` để khám phá dependency framework/ORM/DB qua các sub-package:
-
-```bash
-cd my-monorepo
-npx claudeos-core init
-```
-
-**Những gì được phát hiện:**
-- Dependency từ `apps/web/package.json` (ví dụ: `next`, `react`) → frontend stack
-- Dependency từ `apps/api/package.json` (ví dụ: `express`, `prisma`) → backend stack
-- Dependency từ `packages/db/package.json` (ví dụ: `drizzle-orm`) → ORM/DB
-- Đường dẫn workspace tùy chỉnh từ `pnpm-workspace.yaml` (ví dụ: `services/*`)
-
-**Quét domain cũng bao phủ layout monorepo:**
-- `apps/api/src/modules/*/` và `apps/api/src/*/` cho backend domain
-- `apps/web/app/*/`, `apps/web/src/app/*/`, `apps/web/pages/*/` cho frontend domain
-- `packages/*/src/*/` cho shared package domain
-
-```
-my-monorepo/                    ← Chạy ở đây: npx claudeos-core init
-├── turbo.json                  ← Tự phát hiện là Turborepo
-├── apps/
-│   ├── web/                    ← Next.js phát hiện từ apps/web/package.json
-│   │   ├── app/dashboard/      ← Frontend domain được phát hiện
-│   │   └── package.json        ← { "dependencies": { "next": "^14" } }
-│   └── api/                    ← Express phát hiện từ apps/api/package.json
-│       ├── src/modules/users/  ← Backend domain được phát hiện
-│       └── package.json        ← { "dependencies": { "express": "^4" } }
-├── packages/
-│   ├── db/                     ← Drizzle phát hiện từ packages/db/package.json
-│   └── ui/
-└── package.json                ← { "workspaces": ["apps/*", "packages/*"] }
-```
-
-> **Lưu ý:** Với monorepo Kotlin/Java, phát hiện multi-module dùng `settings.gradle.kts` (xem [Phát Hiện Domain Kotlin Multi-Module](#phát-hiện-domain-kotlin-multi-module) ở trên) và không cần marker monorepo JS.
-
-## Xử Lý Sự Cố
-
-**"claude: command not found"** — Claude Code CLI chưa được cài đặt hoặc không trong PATH. Xem [tài liệu Claude Code](https://code.claude.com/docs/en/overview).
-
-**"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ủa bạn có thể không chuẩn. Xem các pattern phát hiện ở trên cho stack của bạn.
-
-**"0 domains detected" trên dự án Kotlin** — Đảm bảo dự án có `build.gradle.kts` (hoặc `build.gradle` với kotlin plugin) ở root, và file source nằm dưới `**/src/main/kotlin/`. Với dự án multi-module, đảm bảo `settings.gradle.kts` chứa các lệnh `include()`. Dự án Kotlin single-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/`.
-
-**"Language detected as java instead of kotlin"** — ClaudeOS-Core kiểm tra root `build.gradle(.kts)` trước, rồi tới file build submodule. Nếu file build root dùng plugin `java` không có `kotlin`, nhưng submodule dùng Kotlin, công cụ kiểm tra tối đa 5 file build submodule làm fallback. Nếu vẫn không phát hiện, đảm bảo ít nhất một `build.gradle.kts` chứa `kotlin("jvm")` hoặc `org.jetbrains.kotlin`.
-
-**"CQRS not detected"** — Phát hiện kiến trúc dựa trên tên module chứa từ khóa `command` và `query`. Nếu module của bạn dùng tên khác (ví dụ: `write-server`, `read-server`), kiến trúc CQRS sẽ không tự phát hiện. Bạn có thể chỉnh thủ công prompt được tạo sau khi plan-installer chạy.
-
-**"Pass 3 produced 0 rule files under .claude/rules/" (v2.0.0)** — Guard 2 kích hoạt: Claude bỏ qua directive `staging-override.md` và thử ghi trực tiếp vào `.claude/`, nơi chính sách sensitive-path của Claude Code chặn ghi. Chạy lại với `npx claudeos-core init --force`. Nếu lỗi vẫn xuất hiện, kiểm tra `claudeos-core/generated/pass3-prompt.md` để xác nhận block `staging-override.md` ở đầu.
-
-**"Pass 3 finished but N rule file(s) could not be moved from staging" (v2.0.0)** — Guard 1 kích hoạt: việc di chuyển staging gặp khóa file tạm thời (thường là Windows antivirus hoặc file-watcher). Marker KHÔNG được ghi, nên lần chạy `init` tiếp theo tự động retry Pass 3. Chỉ cần chạy lại `npx claudeos-core init`.
-
-**"Pass 3 produced CLAUDE.md and rules but N/9 guide files are missing or empty" (v2.0.0)** — Guard 3 (H2) kích hoạt: Claude bị cắt giữa chừng sau khi viết CLAUDE.md + rules nhưng trước khi hoàn thành (hoặc bắt đầu) mục `claudeos-core/guide/` (mong đợi 9 file). Cũng kích hoạt trên file chỉ có BOM hoặc chỉ có whitespace (heading đã viết nhưng body bị cắt). Không có guard này, completion marker vẫn được ghi, để `guide/` trống vĩnh viễn ở các lần chạy sau. Marker KHÔNG được ghi ở đây, nên lần chạy `init` tiếp theo retry Pass 3 từ cùng kết quả Pass 2. Nếu cứ lặp lại, chạy lại với `npx claudeos-core init --force` để tạo lại từ đầu.
-
-**"Pass 3 finished but the following required output(s) are missing or empty" (v2.0.0, cập nhật v2.1.0)** — Guard 3 (H1) kích hoạt: Claude bị cắt SAU `claudeos-core/guide/` nhưng trước (hoặc trong lúc) `claudeos-core/standard/` hoặc `claudeos-core/skills/`. Yêu cầu: (a) `standard/00.core/01.project-overview.md` tồn tại và không rỗng (sentinel được ghi bởi mọi prompt Pass 3 của mọi stack), (b) `skills/` có ≥1 `.md` không rỗng. `database/` và `mcp-guide/` bị loại trừ có chủ đích (một số stack tạo ra 0 file hợp lệ). `plan/` không còn được kiểm tra kể từ v2.1.0 (master plan đã bị loại bỏ). Đường khôi phục như Guard 3 (H2): chạy lại `init`, hoặc `--force` nếu lỗi vẫn tiếp diễn.
-
-**"Pass 3 split stage crashed partway through (v2.1.0)"** — Khi một trong các split stage (ví dụ: `3b-1`, `3c-2`) lỗi giữa chừng, marker mức stage KHÔNG được ghi, nhưng các stage đã hoàn thành ĐƯỢC ghi trong `pass3-complete.json.groupsCompleted`. Lần chạy `init` tiếp theo đọc mảng này và resume từ stage chưa hoàn thành đầu tiên, bỏ qua mọi công việc đã hoàn thành trước đó. Bạn không cần làm gì thủ công — chỉ cần chạy lại `npx claudeos-core init`. Nếu resume cứ lỗi ở cùng stage, kiểm tra `claudeos-core/generated/pass3-prompt.md` tìm nội dung bị lỗi, rồi thử `--force` để khởi động lại đầy đủ. Shape `pass3-complete.json` (`mode: "split"`, `groupsCompleted: [...]`) ổn định; một marker thiếu hoặc lỗi sẽ khiến toàn bộ Pass 3 chạy lại từ `3a`.
-
-**"Pass 3 stale marker (shape mismatch) — treating as incomplete" (v2.1.0)** — Một `pass3-complete.json` từ lần chạy lời-gọi-đơn pre-v2.1.0 đang được diễn giải theo luật split-mode mới. Kiểm tra shape tìm `mode: "split"` và mảng `groupsCompleted`; nếu thiếu, marker được coi là partial và Pass 3 chạy lại ở split mode. Nếu bạn upgrade từ v2.0.x, điều này xảy ra một lần là mong đợi — lần chạy tiếp theo sẽ ghi shape marker đúng. Không cần hành động.
-
-**"pass2-merged.json exists but is malformed or incomplete (<5 top-level keys), re-running" (v2.0.0)** — Log thông tin, không phải lỗi. Khi resume, `init` giờ parse và validate `pass2-merged.json` (yêu cầu ≥5 top-level key, phản chiếu ngưỡng `INSUFFICIENT_KEYS` của `pass-json-validator`). Skeleton `{}` hoặc JSON lỗi từ lần chạy crash trước tự động bị xóa và Pass 2 chạy lại. Không cần hành động thủ công — pipeline tự chữa. Nếu cứ lặp lại, kiểm tra `claudeos-core/generated/pass2-prompt.md` và retry với `--force`.
+## Đóng góp
 
-**"Static fallback failed while translating to lang='ko'" (v2.0.0)** — Khi `--lang` khác tiếng Anh, Pass 4 / static fallback / gap-fill đều yêu cầu CLI `claude` để dịch. Nếu dịch lỗi (CLI chưa xác thực, timeout mạng, hoặc strict validation từ chối output: <40% độ dài, code fence hỏng, mất frontmatter, v.v.), lần chạy abort thay vì âm thầm ghi tiếng Anh. Sửa: đảm bảo `claude` đã xác thực, hoặc chạy lại với `--lang en` để bỏ qua dịch.
+Chào đón đóng góp — thêm hỗ trợ stack, cải thiện prompt, sửa bug. Xem [CONTRIBUTING.md](CONTRIBUTING.md).
 
-**"pass4-memory.json exists but memory/ is empty" (v2.0.0)** — Lần chạy trước đã ghi marker nhưng người dùng (hoặc script dọn dẹp) xóa `claudeos-core/memory/`. CLI tự phát hiện marker cũ này và chạy lại Pass 4 ở lần `init` tiếp theo. Không cần hành động thủ công.
+Quy tắc ứng xử và chính sách bảo mật xem [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) và [SECURITY.md](SECURITY.md).
 
-**"pass4-memory.json exists but is malformed (missing passNum/memoryFiles) — re-running Pass 4" (v2.0.0)** — Log thông tin, không phải lỗi. Nội dung marker Pass 4 giờ được validate (`passNum === 4` + mảng `memoryFiles` không rỗng), không chỉ sự tồn tại. Một lỗi Claude một phần đã phát ra thứ như `{"error":"timeout"}` làm thân marker trước đây sẽ được chấp nhận như thành công mãi mãi; giờ marker bị xóa và Pass 4 tự chạy lại.
-
-**"Could not delete stale pass3-complete.json / pass4-memory.json" InitError (v2.0.0)** — `init` phát hiện marker cũ (Pass 3: CLAUDE.md bị xóa bên ngoài; Pass 4: memory/ rỗng hoặc thân marker lỗi) và thử xóa, nhưng gọi `unlinkSync` lỗi — thường vì Windows antivirus hoặc file-watcher (editor, IDE indexer) đang giữ file handle. Trước đây điều này bị bỏ qua âm thầm, khiến pipeline bỏ qua pass và dùng lại marker cũ. Giờ nó lỗi rõ ràng. Sửa: đóng mọi editor/AV scanner có thể đang mở file, rồi chạy lại `npx claudeos-core init`.
-
-**"CLAUDEOS_SKIP_TRANSLATION=1 is set but --lang='ko' requires translation" InitError (v2.0.0)** — Bạn đang set env var chỉ dành cho test `CLAUDEOS_SKIP_TRANSLATION=1` trong shell (có thể là sót từ setup CI/test) VÀ chọn `--lang` khác tiếng Anh. Env var này short-circuit đường dịch mà static-fallback và gap-fill của Pass 4 phụ thuộc để output không phải tiếng Anh. `init` phát hiện xung đột lúc chọn ngôn ngữ và abort ngay lập tức (thay vì crash giữa Pass-4 với lỗi lồng khó hiểu). Sửa: hoặc `unset CLAUDEOS_SKIP_TRANSLATION` trước khi chạy, hoặc dùng `npx claudeos-core init --lang en`.
-
-**Cảnh báo "⚠️ v2.2.0 upgrade detected" (v2.2.0)** — `CLAUDE.md` hiện tại được sinh bởi phiên bản trước v2.2.0. Regeneration mặc định ở resume mode sẽ skip các file existing dưới Rule B idempotency, nên các cải tiến cấu trúc v2.2.0 (CLAUDE.md scaffold 8-section, per-file paths trong `40.infra/*`, port accuracy dựa trên `.env.example`, redesign Section 8 `Common Rules & Memory (L4)` (thiết kế lại với hai sub-section: Common Rules · L4 Memory), hàng rule `60.memory/*`, forward-reference `04.doc-writing-guide.md`) sẽ KHÔNG được áp dụng. Fix: chạy lại với `npx claudeos-core init --force`. Nó overwrite file generated (`CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, `claudeos-core/skills/`, `claudeos-core/guide/`) đồng thời giữ nguyên `claudeos-core/memory/` (decision-log, failure-patterns bạn đã tích luỹ — append-only). Commit project trước nếu muốn diff các overwrite.
-
-**Port trong CLAUDE.md khác với `.env.example` (v2.2.0)** — Parser `.env` mới của stack-detector (`lib/env-parser.js`) đọc `.env.example` trước (canonical, committed), rồi các variant `.env` làm fallback. Biến port được nhận diện: `PORT`, `VITE_PORT`, `VITE_DESKTOP_PORT`, `NEXT_PUBLIC_PORT`, `NUXT_PORT`, `DJANGO_PORT`, v.v. Với Spring Boot, `server.port` trong `application.yml` vẫn ưu tiên hơn `.env` (config framework-native thắng). Nếu project dùng tên biến env bất thường, đổi thành convention hoặc mở issue để mở rộng `PORT_VAR_KEYS`. Framework default (Vite 5173, Next.js 3000, Django 8000) chỉ dùng khi cả direct detection lẫn `.env` đều im lặng.
-
-**Giá trị secret bị redact thành `***REDACTED***` trong docs generated (v2.2.0)** — Hành vi mong đợi. Parser `.env` v2.2.0 tự động redact giá trị của biến khớp các pattern `PASSWORD`/`SECRET`/`TOKEN`/`API_KEY`/`CREDENTIAL`/`PRIVATE_KEY` trước khi tới bất kỳ generator nào. Đây là defense-in-depth chống secret bị commit nhầm vào `.env.example`. `DATABASE_URL` giữ nguyên vì back-compat nhận diện DB của stack-detector. Nếu thấy `***REDACTED***` trong `CLAUDE.md` generated thì là bug — giá trị redacted không nên tới bảng; vui lòng báo issue. Config runtime không nhạy cảm (port, host, API target, NODE_ENV, v.v.) vẫn pass qua nguyên vẹn.
-
----
-
-## Đóng Góp
-
-Đóng góp được hoan nghênh! Các khu vực cần giúp đỡ nhất:
-
-- **Template stack mới** — Ruby/Rails, Go (Gin/Fiber/Echo), PHP (Laravel/Symfony), Rust (Axum/Actix), Svelte/SvelteKit, Remix
-- **Tích hợp IDE** — VS Code extension, IntelliJ plugin
-- **Template CI/CD** — ví dụ GitLab CI, CircleCI, Jenkins (GitHub Actions đã có — xem `.github/workflows/test.yml`)
-- **Độ phủ test** — Mở rộng test suite (hiện tại 602 test trên 30 file test bao phủ scanner, phát hiện stack, domain grouping, plan parsing, tạo prompt, CLI selector, phát hiện monorepo, phát hiện Vite SPA, công cụ xác minh, L4 memory scaffold, xác thực resume Pass 2, Pass 3 Guards 1/2/3 (sentinel H1 + empty-file nhận biết BOM H2 + unlink marker cũ nghiêm ngặt), chia batch split-mode Pass 3, resume partial-marker Pass 3 (v2.1.0), xác thực nội dung marker Pass 4 + độ nghiêm ngặt unlink marker cũ + gap-fill scaffoldSkillsManifest (v2.1.0), guard env-skip dịch + fail-fast sớm + CI workflow, di chuyển staged-rules, fallback dịch lang-aware, suite regression loại bỏ master plan (v2.1.0), regression định dạng memory score/compact (v2.1.0), và cấu trúc template AI Work Rules, và trích xuất port/host/API-target từ parser `.env` + redact biến nhạy cảm (v2.2.0))
+## License
 
-Xem [`CONTRIBUTING.md`](./CONTRIBUTING.md) để có danh sách đầy đủ các khu vực, code style, commit convention, và hướng dẫn từng bước để thêm template stack mới.
+[ISC](LICENSE) — miễn phí cho mọi mục đích, kể cả thương mại.
 
 ---
 
-## Tác Giả
-
-Tạo bởi **claudeos-core** — [GitHub](https://github.com/claudeos-core) · [Email](mailto:claudeoscore@gmail.com)
-
-## License
-
-ISC
+<sub>Xây dựng tận tâm bởi [@claudeos-core](https://github.com/claudeos-core). Nếu công cụ này tiết kiệm thời gian cho bạn, một ⭐ trên GitHub giúp nó được nhiều người biết đến.</sub>