# BÁO CÁO KIỂM TOÁN VỆ SINH BÁCH KHOA TOÀN THƯ (WIKI) & TÀI LIỆU KỸ THUẬT FREEEXILE
# FREEEXILE WIKI & DOCUMENTATION HYGIENE AUDIT REPORT

> **Người thực hiện**: Wiki & Documentation Auditor (`explorer_survey_wiki_1`)  
> **Thời điểm kiểm toán**: 2026-10-01T00:48:00Z  
> **Phạm vi kiểm toán**: Toàn bộ tệp bách khoa toàn thư tại `wiki/` (`wiki/vi/`, `wiki/en/`, `wiki/zh/`), toàn bộ tài liệu tại `docs/`, và các công cụ kiểm toán vệ sinh tại `tools/lint/`.

---

## 1. OBSERVATION (QUAN SÁT THỰC TẾ TRỰC TIẾP)

### 1.1. Thống Kê Tổng Thể Hệ Thống Wiki (37 Tệp)
Quét toàn diện thư mục `wiki/` ghi nhận tổng cộng **37 tệp Markdown** phân bổ qua 3 ngôn ngữ chính và 1 tệp chỉ mục gốc:

| Ngôn Ngữ / Thư Mục | Số Lượng Tệp | Tổng Số Dòng | Tổng Dung Lượng | Tệp Ngắn Nhất | Tệp Dài Nhất |
| :--- | :---: | :---: | :---: | :--- | :--- |
| **Gốc (`wiki/`)** | 1 | 86 | 10.974 B | `README.md` (86L) | `README.md` (86L) |
| **Tiếng Việt (`wiki/vi/`)** | 14 | 2.072 | 179.314 B | `ECONOMIC_BALANCE...` (35L) | `CHARACTERS_DESIGN...` (260L) |
| **Tiếng Anh (`wiki/en/`)** | 11 | 1.088 | 84.244 B | `MAPS_DUNGEONS...` (47L) | `QUESTS_AND_MILESTONES...` (208L) |
| **Tiếng Trung (`wiki/zh/`)** | 11 | 823 | 60.106 B | `MAPS_DUNGEONS...` (38L) | `AI_AGENT_ORB...` (134L) |
| **TỔNG CỘNG** | **37** | **4.069** | **334.638 B** | - | - |

#### Danh mục chi tiết 37 tệp Wiki (Line counts, bytes, bảng biểu, liên kết):
1. `wiki\README.md` — 86 dòng, 10.974 bytes | 0 dòng bảng | 33 liên kết `file:///`
2. `wiki\vi\AI_AGENT_ORB_DELEGATION_SPECS.md` — 189 dòng, 15.083 bytes | 18 dòng bảng | 5 liên kết `file:///`
3. `wiki\vi\CHARACTERS_DESIGN_SPECS.md` — 260 dòng, 22.769 bytes | 22 dòng bảng | 0 liên kết
4. `wiki\vi\CORE_LORE_AND_SYSTEMS.md` — 51 dòng, 3.968 bytes | 0 dòng bảng | 1 liên kết `file:///`
5. `wiki\vi\CURRENCIES_AND_SPIRIT_STONES_SPECS.md` — 157 dòng, 12.936 bytes | 12 dòng bảng | 0 liên kết
6. `wiki\vi\ECONOMIC_BALANCE_AND_ANTI_INFLATION_SPECS.md` — 35 dòng, 3.020 bytes | 6 dòng bảng | 2 liên kết `file:///`
7. `wiki\vi\ENDGAME_WORLD_MAP_AND_CONTENT_SPECS.md` — 84 dòng, 7.769 bytes | 7 dòng bảng | 1 liên kết `file:///`
8. `wiki\vi\INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md` — 204 dòng, 15.510 bytes | 21 dòng bảng | 10 liên kết `file:///`
9. `wiki\vi\ITEMS_AND_EQUIPMENT_SPECS.md` — 215 dòng, 16.900 bytes | 15 dòng bảng | 1 liên kết `file:///`
10. `wiki\vi\MAPS_DUNGEONS_AND_SECRET_CHAMBERS_SPECS.md` — 214 dòng, 15.633 bytes | 0 dòng bảng | 12 liên kết `file:///`
11. `wiki\vi\MAP_PROCGEN_WARFOG_ANTIBOT_GUIDE.md` — 48 dòng, 5.220 bytes | 0 dòng bảng | 1 liên kết `file:///`
12. `wiki\vi\MEGA_SHOP_AND_PAYMENTS_SPECS.md` — 156 dòng, 13.608 bytes | 16 dòng bảng | 0 liên kết
13. `wiki\vi\MONSTERS_AND_BOSSES_SPECS.md` — 172 dòng, 13.517 bytes | 21 dòng bảng | 0 liên kết
14. `wiki\vi\PLAYER_HIDEOUT_AND_ASTRAL_PORTALS_SPECS.md` — 58 dòng, 5.524 bytes | 0 dòng bảng | 1 liên kết `file:///`
15. `wiki\vi\QUESTS_AND_MILESTONES_SPECS.md` — 230 dòng, 23.812 bytes | 24 dòng bảng | 21 liên kết `file:///`
16. `wiki\en\AI_AGENT_ORB_DELEGATION_SPECS.md` — 83 dòng, 6.408 bytes | 5 dòng bảng | 1 liên kết `file:///`
17. `wiki\en\CHARACTERS_DESIGN_SPECS.md` — 123 dòng, 8.849 bytes | 10 dòng bảng | 0 liên kết
18. `wiki\en\CORE_LORE_AND_SYSTEMS.md` — 51 dòng, 3.092 bytes | 0 dòng bảng | 1 liên kết `file:///`
19. `wiki\en\CURRENCIES_AND_SPIRIT_STONES_SPECS.md` — 60 dòng, 4.289 bytes | 10 dòng bảng | 0 liên kết
20. `wiki\en\INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md` — 124 dòng, 8.214 bytes | 15 dòng bảng | 8 liên kết `file:///`
21. `wiki\en\ITEMS_AND_EQUIPMENT_SPECS.md` — 105 dòng, 8.361 bytes | 15 dòng bảng | 1 liên kết `file:///`
22. `wiki\en\MAPS_DUNGEONS_AND_SECRET_CHAMBERS_SPECS.md` — 47 dòng, 4.470 bytes | 0 dòng bảng | 8 liên kết `file:///`
23. `wiki\en\MEGA_SHOP_AND_PAYMENTS_SPECS.md` — 126 dòng, 8.337 bytes | 16 dòng bảng | 0 liên kết
24. `wiki\en\MONSTERS_AND_BOSSES_SPECS.md` — 99 dòng, 7.947 bytes | 27 dòng bảng | 0 liên kết
25. `wiki\en\PLAYER_HIDEOUT_AND_ASTRAL_PORTALS_SPECS.md` — 58 dòng, 3.850 bytes | 0 dòng bảng | 1 liên kết `file:///`
26. `wiki\en\QUESTS_AND_MILESTONES_SPECS.md` — 208 dòng, 16.427 bytes | 20 dòng bảng | 17 liên kết `file:///`
27. `wiki\zh\AI_AGENT_ORB_DELEGATION_SPECS.md` — 134 dòng, 9.176 bytes | 14 dòng bảng | 2 liên kết `file:///`
28. `wiki\zh\CHARACTERS_DESIGN_SPECS.md` — 71 dòng, 5.340 bytes | 14 dòng bảng | 0 liên kết
29. `wiki\zh\CORE_LORE_AND_SYSTEMS.md` — 50 dòng, 2.786 bytes | 0 dòng bảng | 1 liên kết `file:///`
30. `wiki\zh\CURRENCIES_AND_SPIRIT_STONES_SPECS.md` — 48 dòng, 3.409 bytes | 4 dòng bảng | 0 liên kết
31. `wiki\zh\INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md` — 124 dòng, 7.918 bytes | 15 dòng bảng | 8 liên kết `file:///`
32. `wiki\zh\ITEMS_AND_EQUIPMENT_SPECS.md` — 53 dòng, 3.942 bytes | 6 dòng bảng | 1 liên kết `file:///`
33. `wiki\zh\MAPS_DUNGEONS_AND_SECRET_CHAMBERS_SPECS.md` — 38 dòng, 3.000 bytes | 0 dòng bảng | 3 liên kết `file:///`
34. `wiki\zh\MEGA_SHOP_AND_PAYMENTS_SPECS.md` — 62 dòng, 3.906 bytes | 0 dòng bảng | 0 liên kết
35. `wiki\zh\MONSTERS_AND_BOSSES_SPECS.md` — 73 dòng, 5.096 bytes | 18 dòng bảng | 0 liên kết
36. `wiki\zh\PLAYER_HIDEOUT_AND_ASTRAL_PORTALS_SPECS.md` — 58 dòng, 3.355 bytes | 0 dòng bảng | 0 liên kết
37. `wiki\zh\QUESTS_AND_MILESTONES_SPECS.md` — 120 dòng, 10.344 bytes | 20 dòng bảng | 17 liên kết `file:///`

### 1.2. Bất Đối Xứng Ngôn Ngữ & Thiếu Hụt Tệp Wiki
1. `wiki/vi/` có **14 tệp**, trong khi `wiki/en/` và `wiki/zh/` chỉ có **11 tệp**.
2. Ba tệp có trong `wiki/vi/` nhưng **HOÀN TOÀN THIẾU** trong `wiki/en/` và `wiki/zh/`:
   - `ECONOMIC_BALANCE_AND_ANTI_INFLATION_SPECS.md`
   - `ENDGAME_WORLD_MAP_AND_CONTENT_SPECS.md`
   - `MAP_PROCGEN_WARFOG_ANTIBOT_GUIDE.md`
3. `wiki/README.md` chỉ mục liên kết 11 tệp trên cả 3 ngôn ngữ, bỏ sót không liên kết 3 tệp trên của Tiếng Việt.

### 1.3. Khảo Sát Tình Trạng Rườm Rà, Văn Xuôi Cảm Tính & Lore Clutter
Trích dẫn trực tiếp các đoạn văn rườm rà, thơ mộng hóa hoặc mô tả xúc cảm làm cản trở tra cứu kỹ thuật:

1. **`wiki/vi/CHARACTERS_DESIGN_SPECS.md`**:
   - Dòng 55-57: Chứa nguyên khối Prompt Midjourney tạo ảnh bằng tiếng Anh chiếm 3 dòng không cần thiết cho tài liệu tra cứu thông số.
   - Dòng 59-63: *"Thanh Phong Kiếm Tông ngự tại Cô Phong Lãnh Nguyệt. Môn đồ chuyên tu kiếm ý lăng lệ, dĩ khí ngự kiếm, thân pháp phiêu dật như cuồng phong, kiếm xuất kinh lôi..."*
   - Dòng 70: *"Lướt sát mặt đất, chân không chạm bụi, để lại vệt gió xé gió"*
   - Dòng 75: *"Thân thể hóa thành kiếm khí tiêu tán giữa hư không"*
   - Dòng 138-140: *"ngự trên Tuyết Sơn Vạn Nhượng. Tông đồ tu luyện Huyền Băng Quyết, tâm tịnh như gương, chân khí biến hóa thành băng tuyết vạn năm đóng băng sinh linh vạn dặm... xiêm y màu lam ngọc pha sương tuyết trắng tinh khiết"*
   - Dòng 177-179: *"tôi luyện đao pháp trong Hỏa Diệm Sơn và Dung Nham Quật. Lấy nộ khí biến thành hỏa diễm, chiêu thức cuồng bạo khai sơn phá thạch, dũng mãnh vô song"*
   - Dòng 216-218: *"Khởi nguồn từ La Hán Cổ Tự chốn thâm sơn Hoang Giới. Các tăng binh khổ hạnh tu luyện Kim Cang Bất Hoại Thần Công... phòng ngự vững chắc như bàn thạch, một bước đi rung chuyển núi non"*

2. **`wiki/vi/MAPS_DUNGEONS_AND_SECRET_CHAMBERS_SPECS.md`**:
   - **Tệp dài 214 dòng nhưng KHÔNG CÓ BẤT KỲ DÒNG BẢNG BIỂU NÀO (0 Table Lines)**. Toàn bộ 10 phân khu, hầm ngục và bí thất đều được viết bằng bullet list và văn xuôi tả cảnh:
   - Dòng 12: *"Không có tiên nhân, không có phi thăng, không có tông môn tiên cảnh; chỉ có máu, xương, sắt rỉ, cổ cốt và dã thú cuồng loạn."*
   - Dòng 66: *"lều da rách rưới, đống lửa than cháy âm ỉ xua tan giá lạnh"*
   - Dòng 79: *"khung xương sườn thủy quái dạt vào bờ cát đen, sóng biển gầm thét dữ dội"*
   - Dòng 90: *"ngập ngụa bùn tanh và xác thú thối rữa, sương mù độc hại bốc lên từ các hố than bùn ngập máu đen"*
   - Dòng 99-100: *"Bão cát cuồng phong... gió cát cào rách da thịt... Sa mạc khô cằn trơ trọi xương sườn cự thú hóa thạch khổng lồ nhô khỏi cát vàng bỏng rát"*

3. **`wiki/vi/ITEMS_AND_EQUIPMENT_SPECS.md`**:
   - Mỗi thần binh lặp lại 1 khối Concept Art Prompt 3 dòng và 3-5 dòng văn học miêu tả:
   - Dòng 49: *"Thân kiếm thanh mảnh đúc từ Cửu Thiên Huyền Thiết, lưỡi kiếm sáng lấp lánh như mặt hồ băng, chuôi kiếm bọc lụa trắng điểm ngọc bích phong lôi..."*
   - Dòng 63: *"sống đao dày hình răng cưa hung tợn, lưỡi đao nung đỏ như dung nham mới rút từ lò luyện ngục. Khói đen và tàn lửa bốc lên không ngừng từ các rãnh huyết."*
   - Dòng 76: *"Cánh cung uốn lượn hình cánh phượng hoàng kim sí, dây cung bện từ gân rồng viễn cổ phát sáng ánh kim rực rỡ..."*

4. **`wiki/vi/MONSTERS_AND_BOSSES_SPECS.md`**:
   - Dòng 94-96: *"Quái xà đầm lầy khổng lồ dài hơn 35m, lớp da sần sùi đóng vảy đen bóng nhẫy dịch mật độc màu lam tím. Cặp sừng gai xương gãy vụn rỉ ra nọc độc ăn mòn, đôi mắt đục ngầu vô hồn phát quang buốt giá..."*
   - Dòng 56: *"Thân thể khô quắt quấn vải liệm rách rưới, tay phải cầm kiếm rỉ sét, di chuyển lê lết nhưng vung kiếm chém bất ngờ cực kỳ sắc bén"*

5. **`wiki/vi/ENDGAME_WORLD_MAP_AND_CONTENT_SPECS.md`**:
   - Dòng 43: *"Vết rách màu tím đen ngòm trên mặt đất bốc hơi tử khí... xé toạc địa hình, liên tục phun ra bầy bọ ăn xác..."*
   - Dòng 58: *"Cổng máu thịt phập phồng như nhịp tim của quái vật"*
   - Dòng 68: *"Hốc đá ngầm có ngọn đuốc mỡ người le lói"*

### 1.4. Kết Quả Kiểm Tra Với `tools/lint/check_code_and_doc_hygiene.py`
Chạy lệnh trực tiếp:
```bash
python tools/lint/check_code_and_doc_hygiene.py
```
- **Kết quả trả về**: Exit Code `0` (Không có lỗi ERROR).
- **Thống kê tổng số**: 674 tệp (351 code, 323 docs). Trong đó có 644 tệp sạch sẽ hoàn toàn.
- **Tài liệu vượt Soft Cap (>400 dòng, Hard Cap là 600 dòng)**:
  - `docs\standards\ENGINEERING_STANDARDS_2026.md` (514 dòng) -> Cảnh báo Soft Cap, chưa vi phạm Hard Cap.
  - Các tệp handoff cũ trong `.agents\teamwork\`: `explorer_m1_3_gen2\handoff.md` (486 dòng), `explorer_m2_2\handoff.md` (470 dòng).
- **Kết luận ngưỡng độ dài**: 100% tệp trong `wiki/` (cao nhất 260 dòng) và `docs/` đều **TUÂN THỦ HOÀN TOÀN HARD CAP (<= 600 dòng)**.

### 1.5. Kết Quả Kiểm Tra Với `tools/lint/check_documentation_system.py`
Chạy lệnh trực tiếp:
```bash
python tools/lint/check_documentation_system.py
```
- **Kết quả trả về**: Exit Code `1` (AUDIT THẤT BẠI do có lỗi ERROR).
- **Chi tiết lỗi phát hiện**:
  1. `❌ [MISSING_FRONTMATTER] docs\standards\POE2_GAMEPLAY_AND_ZONE_ARCHITECTURE.md`: Tệp thiếu khối metadata YAML Frontmatter chuẩn (`---`) ở đầu tệp.
  2. `⚠️ [SOFT_CAP_EXCEEDED] docs\standards\ENGINEERING_STANDARDS_2026.md`: 514 dòng > 400 dòng (Soft Cap).

### 1.6. Kết Quả Kiểm Tra Tính Toàn Vẹn Liên Kết Clickable (`file:///...`)
Chạy kiểm tra tự động qua script phân tích liên kết toàn bộ repository:
- **Tệp Wiki**: 157 liên kết dạng `file:///`. Phát hiện **3 liên kết hỏng (BROKEN)**:
  1. `wiki\en\INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md`: `file:///c:/Projects/FreeExile/server/world/consignment_vault.py` -> Tệp không tồn tại! (Thực tế tệp nằm tại: `server/trade/consignment_vault.py`).
  2. `wiki\vi\INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md`: `file:///c:/Projects/FreeExile/server/world/consignment_vault.py` -> Tệp không tồn tại! (Thực tế: `server/trade/consignment_vault.py`).
  3. `wiki\zh\INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md`: `file:///c:/Projects/FreeExile/server/world/consignment_vault.py` -> Tệp không tồn tại! (Thực tế: `server/trade/consignment_vault.py`).
- **Tệp Docs**: 349 liên kết dạng `file:///`. Phát hiện **1 liên kết hỏng (BROKEN)**:
  1. `docs\design_requests\approved\DRQ-20260929-FERAL-NPC-CAST.md`: `file:///c:/Projects/FreeExile/docs/NPC_SYSTEM_ARCHITECTURE.md` -> Tệp không tồn tại! (Thực tế tệp nằm tại: `docs/game_design/NPC_SYSTEM_ARCHITECTURE.md`).

---

## 2. LOGIC CHAIN (CHUỖI SUY LUẬN TỪ QUAN SÁT ĐẾN KẾT LUẬN)

1. **Từ Quan Sát 1.1 & 1.3**:
   - `wiki/vi/` có kích thước tệp lớn gấp 2 đến 3 lần so với `wiki/zh/` và `wiki/en/` (ví dụ `CHARACTERS_DESIGN_SPECS.md`: VI 260 dòng vs EN 123 dòng vs ZH 71 dòng; `MAPS_DUNGEONS...`: VI 214 dòng vs EN 47 dòng vs ZH 38 dòng).
   - Sự phình to này không bắt nguồn từ thông số kỹ thuật (cả 3 bản đều có chung ID, hitbox, tốc độ di chuyển, frame budget), mà xuất phát hoàn toàn từ:
     a) Các đoạn văn tả cảnh dài dòng, lãng mạn hóa võ hiệp hoặc kinh dị hóa man tộc.
     b) Khối prompt tạo ảnh AI (Midjourney prompt blocks) chiếm nhiều dòng.
     c) Cấu trúc danh sách lặp lại (bullet points lặp đi lặp lại nhãn ID, Mô Tả, Thông Số...) thay vì gom vào Bảng Tra Cứu (Reference Matrix).
   - *Hệ quả*: Khi lập trình viên, designer hoặc người chơi cần tra cứu nhanh hitbox radius, frame animation, metal shader profile hay drop rate, họ phải cuộn chuột qua hàng chục khổ văn xuôi gây nhiễu nhận thức nghiêm trọng.

2. **Từ Quan Sát 1.2**:
   - `wiki/vi/` sở hữu 3 tệp đặc tả kinh tế và bản đồ rất giá trị (`ECONOMIC_BALANCE_AND_ANTI_INFLATION_SPECS.md`, `ENDGAME_WORLD_MAP_AND_CONTENT_SPECS.md`, `MAP_PROCGEN_WARFOG_ANTIBOT_GUIDE.md`) nhưng chưa được đồng bộ hóa dịch sang Tiếng Anh (`wiki/en/`) và Tiếng Trung (`wiki/zh/`).
   - Điều này vi phạm tính đồng bộ của hệ thống Master Lexicon & Bách khoa toàn thư đa ngôn ngữ được yêu cầu tại mục `## 2026-10-01T00:40:31Z` (R3 & R4).

3. **Từ Quan Sát 1.4 & 1.5**:
   - `tools/lint/check_code_and_doc_hygiene.py` tập trung vào kiểm soát độ dài file (`.md` cap 400/600), không bắt lỗi thiếu frontmatter hay liên kết hỏng.
   - `tools/lint/check_documentation_system.py` kiểm soát frontmatter và clickable links nhưng **chỉ quét trong `docs/` mà bỏ quên thư mục `wiki/`**.
   - Tệp `docs/standards/POE2_GAMEPLAY_AND_ZONE_ARCHITECTURE.md` là văn bản chỉ đạo mới ban hành nhưng thiếu YAML Frontmatter chuẩn, khiến công cụ `check_documentation_system.py` báo đỏ (FAIL).

4. **Từ Quan Sát 1.6**:
   - Cả 3 tệp đặc tả hòm đồ `INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md` trên cả 3 thứ tiếng đều trỏ sai đường dẫn `server/world/consignment_vault.py` thay vì `server/trade/consignment_vault.py`.
   - Một liên kết trong Design Request trỏ thiếu thư mục con `game_design/`.
   - Điều này chứng minh sự cần thiết phải mở rộng phạm vi kiểm tra liên kết tự động sang cả thư mục `wiki/`.

---

## 3. CAVEATS (GIỚI HẠN & GIẢ ĐỊNH)

1. **Giới hạn quyền can thiệp**: Theo nguyên tắc Read-Only Investigation của Explorer Agent, cuộc khảo sát này không trực tiếp sửa đổi nội dung tệp trong `wiki/` hay `docs/`. Mọi đề xuất chuyển đổi được cung cấp dưới dạng sơ đồ chuyển đổi (Mapping Matrix) và cấu trúc mẫu để Đội ngũ Triển khai (Lead Documentation Architect / Implementer) áp dụng.
2. **Bảo tồn giá trị Lore**: Việc loại bỏ văn xuôi rườm rà khỏi các tệp Tra Cứu (Reference Specs) không đồng nghĩa với việc xóa bỏ hoàn toàn Lore của trò chơi. Lore và bối cảnh cốt truyện cần được gom về đúng vị trí phân loại của Diátaxis: tệp Giải Thích / Bối Cảnh Cốt Truyện (`Explanation / World Lore`), ví dụ `wiki/vi/CORE_LORE_AND_SYSTEMS.md` hoặc `docs/lore/`, trả lại không gian súc tích cho các tệp Reference.
3. **Phạm vi ngôn ngữ**: Hệ thống Wiki hiện tại lưu trữ 3 ngôn ngữ cốt lõi (VI, EN, ZH). Sáu ngôn ngữ còn lại trong 9 ngôn ngữ (JA, KO, TH, DE, RU, ES) hiện được quản lý tại tầng Microcopy Catalog (`client/webapp/js/data/i18n_catalog.js`).

---

## 4. CONCLUSION (ĐÁNH GIÁ TỔNG KẾT & PHƯƠNG ÁN CHUYỂN ĐỔI)

### 4.1. Đánh Giá Hiện Trạng Vệ Sinh
- **Tuân thủ Độ Dài**: 100% tệp `wiki/` và `docs/` tuân thủ Hard Cap 600 dòng. Không có tệp tài liệu nào bị lỗi vi phạm Hard Cap.
- **Điểm Nghẽn Mật Độ Thông Tin**: `wiki/vi/` bị ô nhiễm bởi văn xuôi tả cảnh và prompt Midjourney (mật độ thông số kỹ thuật thực tế chỉ chiếm ~35% diện tích văn bản).
- **Lỗi Cần Khắc Phục Tức Thì**:
  1. Thiếu YAML frontmatter tại `docs/standards/POE2_GAMEPLAY_AND_ZONE_ARCHITECTURE.md`.
  2. Đường dẫn hỏng `server/world/consignment_vault.py` trong 3 tệp Wiki kho đồ.
  3. Thiếu 3 tệp đồng bộ tại `wiki/en/` và `wiki/zh/`.

---

### 4.2. Ma Trận Quy Đổi Diátaxis: Từ Văn Xuôi Sang Bảng Tra Cứu Thông Số (Diátaxis Reference Conversion Map)

Để biến các tệp Wiki thành chuẩn **Diátaxis Reference** (tra cứu thông số trong < 3 giây), dưới đây là thiết kế chuẩn hóa cho từng nhóm tệp:

#### A. Chuyển Đổi Nhóm Nhân Vật (`CHARACTERS_DESIGN_SPECS.md`)
- **Trước chuyển đổi**: Mỗi môn phái chiếm 40-50 dòng với khối Prompt Midjourney, văn xuôi xuất xứ môn phái, và 10 bullet points rải rác.
- **Sau chuyển đổi**:
  1. Loại bỏ hoàn toàn khối `[Visual Concept Art Prompt]`.
  2. Rút gọn xuất xứ thành 1 câu duy nhất.
  3. Gom toàn bộ thông số vào **Bảng Thông Số Kỹ Thuật 5 Môn Phái**:

```markdown
| Mã ID | Môn Phái & Khóa | Hệ | Hitbox ($r \times h$) | Tốc Độ | Sprite Budget | Metal Shader | Emissive Hex | Haptics iOS |
| :--- | :--- | :---: | :---: | :---: | :---: | :--- | :---: | :--- |
| `char_class_azure_wind_sword` | Thanh Phong Kiếm Tông (`class.azure_wind_sword.name`) | Kim | $0.42m \times 1.80m$ | $6.2 m/s$ | 102f | `MetalPBR_Anisotropic` | `#E0F7FA` | Transient (0.65, 0.90) |
| `char_class_nether_venom_herbalist` | U Minh Độc Y (`class.nether_venom.name`) | Mộc | $0.40m \times 1.72m$ | $6.0 m/s$ | 104f | `MetalPBR_SubsurfaceBio` | `#00E676` | Continuous (120Hz, 0.45) |
| `char_class_glacial_frost_temple` | Hàn Băng Thần Điện (`class.glacial_frost.name`) | Thủy | $0.40m \times 1.75m$ | $6.1 m/s$ | 100f | `MetalPBR_GlassRefraction` | `#00B0FF` | Dual Transient (0.80) |
| `char_class_infernal_berserker_blade` | Liệt Diễm Cuồng Đao (`class.infernal_blade.name`) | Hỏa | $0.55m \times 2.05m$ | $5.8 m/s$ | 108f | `MetalPBR_HeatDistort` | `#FF3D00` | Heavy Transient (1.00) + Shake |
| `char_class_vajra_titan_arhat` | Kim Cang La Hán (`class.vajra_titan.name`) | Thổ | $0.60m \times 2.10m$ | $5.5 m/s$ | 99f | `MetalPBR_BronzeMetallic` | `#FFD700` | Deep Transient (0.90, 0.40) |
```

#### B. Chuyển Đổi Nhóm Bản Đồ & Vùng Đất Chết (`MAPS_DUNGEONS_AND_SECRET_CHAMBERS_SPECS.md`)
- **Trước chuyển đổi**: 214 dòng văn xuôi, 0 bảng biểu, mô tả sỏi đá, bùn lầy, lửa than.
- **Sau chuyển đổi**: Chuyển thành 3 bảng tra cứu độc lập theo chuẩn Diátaxis:

##### 1. Bảng Tra Cứu 10 Đại Phân Khu Thế Giới:
```markdown
| Mã ID Zone | Tên Khu Vực | Cấp Độ | Môi Trường Hazard | Boss / Quái Vật Chủ Lực | Trụ Thần Hành (Waypost) | Passages Liên Kết |
| :--- | :--- | :---: | :--- | :--- | :--- | :--- |
| `zone_boundless_sanctuary` | Doanh Trại Bến Lưu Đày | 1-100 | Sanctuary (An Toàn 100%) | Không có (Chỉ Target Dummy) | `wp_sanctuary_central` (0, 0) | Ra Táng Kiếm Nhai |
| `zone_tang_kiem_nhai` | Bờ Đá Tàn Xương | 1-10 | Bãi đá sóng dập | Hoang Giới Thi Cẩu (`mob_trash_bone_hound`) | `wp_tang_kiem_nhai` (120, -45) | Sanctuary <-> Cổ Kiếm Trũng |
| `zone_ancient_sword_barrow` | Đầm Lầy Thối Rữa | 8-20 | Chướng khí độc (`MIASMA_TOXIC`) | U Hồn Kiếm Nô (`mob_trash_ghost_sword_thrall`) | `wp_ancient_sword` (280, -90) | Táng Kiếm <-> Sa Cốt |
| `zone_boundless_sandstorm` | Sa Cốt Hoang Mạc | 20-35 | Bão cát giảm 50% tầm nhìn | Hóa Thạch Cốt Thú | `wp_sandstorm_oasis` (450, -120) | Đầm Lầy <-> Phế Tích |
| `zone_blood_scale_ruins` | Phế Tích Xẻ Thịt | 30-45 | Huyết Tế Cổ Trận | Bại Tướng Cuồng Sát | `wp_blood_scale` (600, -80) | Sa Cốt <-> Tế Đàn |
| `zone_five_elements_altar` | Tế Đàn Man Hoang | 40-55 | Từ trường Ngũ Hành | Thú Tổ Hộ Vệ (5 Hành) | `wp_primal_altar` (750, 0) | Phế Tích <-> Đầm Băng |
| `zone_abyssal_ice_pond` | Vực Đầm Băng Độc | 50-65 | Đầm lầy băng hàn làm chậm | Xà Quái Vực Sâu (`boss_world_abyssal...`) | `wp_abyssal_pond` (880, 110) | Tế Đàn <-> Vực Đói |
| `zone_infinite_blood_rift` | Vực Đói Nuốt Chửng | 60-75 | Khe nứt rỉ máu rút HP | Thao Thiết Cốt Thú (`boss_world_bone_glutton...`)| `wp_blood_rift` (1020, 230) | Đầm Băng <-> Miệng Lửa |
| `zone_purgatory_lava_cavern`| Miệng Lửa Nung Máu | 70-85 | Nham thạch sôi sục | Cự Thú Nham Thạch (`boss_world_blazing...`) | `wp_lava_cavern` (1200, 350) | Vực Đói <-> Bệ Thờ Quỷ |
| `zone_boundless_celestial_palace`| Bệ Thờ Quỷ Đoạt Mệnh | 85-100| Vực thẳm hư không | Đoạn Độc Hành (`boss_world_nine_nether...`) | `wp_celestial_apex` (1450, 500) | Điểm Cuối Hoang Vực |
```

##### 2. Bảng Tra Cứu Hầm Ngục (Dungeon Instances):
```markdown
| Mã ID Instance | Tên Hầm Ngục | Số Tầng | Thời Gian | Số Mạng Sống | Boss Cuối | Phần Thưởng Bản Vị & Danh Hiệu |
| :--- | :--- | :---: | :---: | :---: | :--- | :--- |
| `inst_phong_ma_co_tran` | Hầm Ngục Phong Thú | 50 tầng | 30 phút | 3 mạng | Xà Quái Vực Sâu (Tầng 50) | 40 Huyết Hồn Thạch, 8 Cổ Cốt Ấn, +12 Huyệt Vị, *Trảm Thú Dũng Giả* |
| `inst_bi_canh_hu_khong` | Cõi Tuyệt Địa Hư Không | 100 tầng | 60 phút | 1 mạng (Hardcore) | Thao Thiết Cổ Ma (Tầng 100) | 2 Huyết Ảnh Cổ Kính, 150 Huyết Hồn Thạch, +30 Huyệt Vị, *Tuyệt Địa Độc Tôn* |
| `inst_van_gioi_thi_luyen` | Đấu Trường Man Hoang | 3 đợt | 10 phút | 3 mạng | Đợt sóng quái dồn dập | Rương tài nguyên chế tác ngẫu nhiên |
```

##### 3. Bảng Tra Cứu Mật Thất Bí Ẩn (Cryptic Secret Chambers):
```markdown
| Mã ID Bí Thất | Tên Mật Thất | Vùng Đất Kích Hoạt | Điều Kiện Huyền Bí (Trigger) | Thời Gian Tồn Tại | Danh Hiệu Trao Tặng |
| :--- | :--- | :--- | :--- | :---: | :--- |
| `secret_huyen_anh_to_su` | Bí Thất Xà Ảnh | Phế Tích Xẻ Thịt | HP < 10% & tung Huyễn Ảnh Bộ né lethal strike | 10 phút đếm lùi | *Huyễn Ảnh Thần Bộ* |
| `secret_tan_bi_than_tuong` | Hầm Mộ Chiến Binh | Sa Cốt Hoang Mạc | Dâng 3 Cốt Đinh tại Bia Đá Cổ giữa bão cát | 15 phút đếm lùi | *Bất Diệt Chiến Hồn* |
| `secret_ngu_hanh_tran_nhan` | Mắt Trận Thú Tổ | Tế Đàn Man Hoang | Kích hoạt 5 trụ thú tổ theo vòng tương sinh | 10 phút đếm lùi | *Man Thú Chúa Tể* |
| `secret_tang_kiem_kiem_chung` | Cổ Kiếm Tế Đàn | Bờ Đá Tàn Xương | Rửa đao gãy tại mỏm đá rỉ máu vào nửa đêm | 12 phút đếm lùi | *Huyết Kiếm Bất Tử* |
```

#### C. Chuyển Đổi Nhóm Thần Binh Trang Bị (`ITEMS_AND_EQUIPMENT_SPECS.md`)
- **Trước chuyển đổi**: 8 thần binh chiếm 120 dòng với các đoạn miêu tả lụa là, hồ băng, cánh phượng.
- **Sau chuyển đổi**: Chuyển thành **Bảng Thông Số Bát Đại Thần Binh**:

```markdown
| Mã ID Thần Binh | Tên Vũ Khí | Hành | Lưới (W x H) | Tầm Đánh | Tốc Độ Ra Đòn | Metal Shader | Đặc Trưng Chiến Đấu |
| :--- | :--- | :---: | :---: | :---: | :---: | :--- | :--- |
| `item_wpn_azure_wind_sword` | Thanh Phong Cổ Kiếm | Kim | $1 \times 3$ | $2.2m$ ($120^\circ$) | $1.45$/s | `Wpn_Shader_EdgeReflection` | Tốc đánh nhanh, xuyên giáp, bạo kích |
| `item_wpn_infernal_executioner_blade` | Xích Diễm Trảm Mã Đao | Hỏa | $2 \times 4$ | $2.8m$ ($180^\circ$) | $0.95$/s | `Wpn_Shader_HeatEmissiveDistort` | Sát thương cực đại, nổ diện rộng, phá thế |
| `item_wpn_sun_piercing_bow` | Xạ Nhật Thần Cung | Kim-Hỏa| $2 \times 3$ | $14.0m$ ($28m/s$) | $1.20$/s | `Wpn_Shader_LaserDrawTrail` | Tầm bắn siêu xa, đạn đạo xuyên thấu |
| `item_wpn_glacial_frost_staff` | Băng Phách Hàn Liên Trượng | Thủy | $1 \times 4$ | $12.0m$ (Phép) | $1.05$/s | `Wpn_Shader_SubsurfaceFrost` | Khống chế đóng băng, làm chậm diện rộng |
| `item_wpn_break_army_spear` | Phá Quân Huyền Thiết Thương | Kim-Thổ| $1 \times 4$ | $3.5m$ ($30^\circ$) | $1.30$/s | `Wpn_Shader_MetallicSpear` | Đâm thẳng tầm trung, lướt kích xung phong |
| `item_wpn_nether_blood_claw` | U Minh Huyết Độc Trảo | Mộc | $2 \times 2$ | $1.6m$ | $1.75$/s | `Wpn_Shader_VenomDrip` | Tốc độ cực nhanh, dồn độc DoT, hút máu |
| `item_wpn_vajra_bronze_spade` | Hàng Ma Đồng Thiền Trượng | Thổ | $2 \times 4$ | $2.6m$ | $0.90$/s | `Wpn_Shader_BronzeMonk` | Choáng diện rộng, tạo khiên hộ thể |
| `item_wpn_void_severing_twin_daggers`| Đoạn Không Song Thích | Hư Không| $1 \times 2$ | $1.5m$ | $1.65$/s | `Wpn_Shader_VoidDistort` | Tàng hình, đâm lén sau lưng sát thương x3 |
```

#### D. Chuyển Đổi Nhóm Tiền Tệ Bản Vị (`CURRENCIES_AND_SPIRIT_STONES_SPECS.md`)
- **Trước chuyển đổi**: 157 dòng với các đoạn mô tả tinh thể bát diện, khói tường vân ngũ sắc.
- **Sau chuyển đổi**: Chuyển thành **Bảng Thông Số 10 Tiền Tệ Bản Vị Chế Tác**:

```markdown
| Mã ID Tiền Tệ | Tên Linh Thạch / Phù | Phân Cấp Bản Vị | Công Năng Chế Tác (Crafting Effect) | Xếp Chồng | Loot Beam | Tần Số Âm / Haptic |
| :--- | :--- | :---: | :--- | :---: | :---: | :--- |
| `currency_primal_chaos_stone` | Huyết Hồn Thạch | Chuẩn toàn server | Tẩy sạch và tái tạo ngẫu nhiên toàn bộ $4-6$ dòng trên đồ Cực Phẩm | 20 | Vàng cam 15m | $850Hz$ trầm / Rung nảy đầm ($0.75$) |
| `currency_destiny_rune` | Cổ Cốt Ấn | Cao cấp | Đảo ngẫu nhiên lại toàn bộ biên độ min-max của các dòng hiện có | 20 | Hoàng kim 25m | $2.4kHz$ chuông ngọc / Rung nảy kép |
| `currency_sovereign_sigil` | U Minh Cốt Đinh | Nâng cấp thần binh | Khảm thêm 1 dòng Cực Phẩm mới vào ô thuộc tính còn trống | 20 | Tím sấm 20m | Sấm sét ngân vang / Transient sắc |
| `currency_void_mirror_relic` | Huyết Ảnh Cổ Kính | Thần vật tối thượng | Nhân bản 1 trang bị hiếm thành bản sao [Thái Hư Huyễn Ảnh] | 1 (Độc bản) | Bạc xuyên mây | Đại hồng chung toàn map / Rung dài 1.5s |
| `currency_awakening_pearl` | Hắc Sơ Thạch | Cơ bản | Nâng cấp trang bị Phàm Phẩm (Trắng) thành Linh Phẩm (Xanh lam) | 40 | Lam nhạt 5m | Tiếng keng nhẹ / Haptic 0.30 |
| `currency_creation_stone` | Uẩn Ma Thạch | Cơ bản | Nâng cấp trang bị Phàm Phẩm (Trắng) trực tiếp thành Cực Phẩm (Vàng) | 20 | Hổ phách 10m | Tiếng kim ngân / Haptic 0.50 |
| `currency_marrow_cleansing_pill`| Tẩy Tủy Đan | Dược đan | Tẩy và hoàn trả 1 điểm huyệt vị trên Huyết Cốt Ma Đồ | 20 | Lục ngọc 8m | Tiếng đan dược rơi / Haptic nhẹ |
| `currency_boundary_transcendence_dust`| Hóa Cảnh Sa | Cứu phôi | Xóa ngẫu nhiên 1 dòng thuộc tính trên trang bị Cực Phẩm | 20 | Bạc mờ 5m | Tiếng cát rơi / Rung mịn |
| `currency_primal_scouring_stone`| Chân Linh Tiết Thạch | Tẩy trắng | Xóa sạch toàn bộ thuộc tính, đưa trang bị về phôi Trắng ban đầu | 30 | Xám mờ 3m | Tiếng gõ đá thô / Không rung |
| `currency_elemental_essence_shard`| Ngũ Hành Tinh Phiến | Mảnh ghép | Ghép 20 mảnh thành 1 viên Huyết Hồn Thạch hoàn chỉnh | 100 | Ngũ sắc 5m | Tiếng pha lê va chạm / Haptic nhẹ |
```

#### E. Chuyển Đổi Nhóm Quái Vật & Boss (`MONSTERS_AND_BOSSES_SPECS.md`)
- **Trước chuyển đổi**: 172 dòng với văn bản mô tả răng nanh nhọn hoắt, mắt đục ngầu vô hồn.
- **Sau chuyển đổi**: Chuyển thành **Bảng Ma Trận Quái Vật & Đại Boss Toàn Thông Số** (Học tập theo mẫu bảng Section 5 của bản Tiếng Trung `wiki/zh/MONSTERS_AND_BOSSES_SPECS.md`):

```markdown
| Mã ID Thực Thể | Tên Quái / Boss | Cấp Bậc | Hệ Nguyên Tố | Hitbox ($r$) | Tốc Độ | Vị Trí Ngự Trị | Cơ Chế Tác Chiến Chủ Lực |
| :--- | :--- | :---: | :---: | :---: | :---: | :--- | :--- |
| `mob_trash_bone_hound` | Hoang Giới Thi Cẩu | Dã Quái | Vật lý | $0.35m$ | $7.2 m/s$ | Bờ Đá Tàn Xương | Bầy đàn 10-40 con, áp sát cắn xé |
| `mob_trash_ghost_sword_thrall`| U Hồn Kiếm Nô | Dã Quái | Âm Sát | $0.40m$ | $3.8 m/s$ | Đầm Lầy Thối Rữa | Vung kiếm bất ngờ, khói tử khí |
| `affix_elite_*` | Quái Tinh Anh | Tinh Anh | Ngẫu nhiên | $0.50-0.70m$ | $5.5-8.0 m/s$ | Toàn bản đồ | 2-4 affixes (Lôi Đạn, Bộc Hỏa, Kim Cang) |
| `boss_world_abyssal_dragon_king`| Xà Quái Vực Sâu | Thế Giới | Thủy - Độc | $1.5 - 2.2m$ | $6.5 m/s$ | Vực Đầm Băng Độc | 3 Phase: Quét đuôi 180°, Vòi rồng bùn, Mưa axit |
| `boss_world_bone_glutton_taotie`| Thao Thiết Cốt Thú | Thế Giới | Thổ - Hư Không| $3.50m$ | $4.2 m/s$ | Vực Đói Nuốt Chửng | Hút chân không hấp dẫn, chấn địa gai xương |
| `boss_world_nine_nether_sovereign`| Đoạn Độc Hành | Thế Giới | Kim - Hỏa | $0.65m$ | $9.5 m/s$ | Bệ Thờ Quỷ Đoạt Mệnh | Áp sát tức thì, lốc xoáy trảm kích 8 thức |
| `boss_world_blazing_fire_pixiu` | Cự Thú Nham Thạch | Thế Giới | Hỏa - Kim | $2.80m$ | $5.8 m/s$ | Miệng Lửa Nung Máu | Phun lửa 360°, bão thiên thạch rơi tự do |
```

---

## 5. VERIFICATION METHOD (PHƯƠNG PHÁP KIỂM CHỨNG ĐỘC LẬP)

Để kiểm chứng độc lập các phát hiện và đánh giá trong báo cáo này, bất kỳ Agent nào cũng có thể thực thi các lệnh sau:

### 5.1. Kiểm Chứng Độ Dài & Vệ Sinh Tài Liệu
```bash
python tools/lint/check_code_and_doc_hygiene.py --strict
```
- **Kỳ vọng**: Exit code `0`.
- **Xác nhận**: Không có tệp nào vượt quá Hard Cap 600 dòng. Tệp `docs/standards/ENGINEERING_STANDARDS_2026.md` nằm ở mức 514 dòng (cảnh báo Soft Cap).

### 5.2. Kiểm Chứng Cấu Trúc Docs-as-Code & Frontmatter
```bash
python tools/lint/check_documentation_system.py
```
- **Kỳ vọng**: Exit code `1` (FAIL).
- **Lý do**: Phát hiện lỗi `MISSING_FRONTMATTER` tại `docs/standards/POE2_GAMEPLAY_AND_ZONE_ARCHITECTURE.md`.

### 5.3. Kiểm Chứng Tính Hợp Lệ Của Liên Kết
Chạy script kiểm tra liên kết:
```bash
python .agents/teamwork/explorer_survey_wiki_1/check_links.py
```
- **Xác nhận lỗi liên kết Wiki**:
  - `wiki/en/INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md`
  - `wiki/vi/INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md`
  - `wiki/zh/INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md`
  Cả 3 tệp cùng trỏ đến `file:///c:/Projects/FreeExile/server/world/consignment_vault.py` không tồn tại.
- **Xác nhận lỗi liên kết Docs**:
  - `docs/design_requests/approved/DRQ-20260929-FERAL-NPC-CAST.md` trỏ đến `file:///c:/Projects/FreeExile/docs/NPC_SYSTEM_ARCHITECTURE.md` không tồn tại.

---

## 6. KIẾN NGHỊ HÀNH ĐỘNG DÀNH CHO LEAD DOCUMENTATION ARCHITECT

1. **Khắc phục lỗi Frontmatter**: Bổ sung khối YAML metadata chuẩn vào đầu tệp `docs/standards/POE2_GAMEPLAY_AND_ZONE_ARCHITECTURE.md` để đưa `check_documentation_system.py` về trạng thái 100% Green.
2. **Sửa 3 liên kết hỏng trong Wiki**: Thay thế `server/world/consignment_vault.py` bằng `server/trade/consignment_vault.py` trong cả 3 tệp `INVENTORY_STASH_AND_SPATIAL_GRID_SPECS.md`.
3. **Đồng bộ hóa 3 tệp thiếu**: Dịch và tạo phiên bản `en/` và `zh/` cho:
   - `ECONOMIC_BALANCE_AND_ANTI_INFLATION_SPECS.md`
   - `ENDGAME_WORLD_MAP_AND_CONTENT_SPECS.md`
   - `MAP_PROCGEN_WARFOG_ANTIBOT_GUIDE.md`
   Đồng thời bổ sung liên kết vào `wiki/README.md`.
4. **Áp dụng bảng tra cứu Diátaxis**: Thay thế các đoạn văn tả cảnh rườm rà trong `wiki/vi/` theo 5 ma trận đặc tả đã thiết kế ở Mục 4.2 của báo cáo này, giảm kích thước `wiki/vi/` từ 2.072 dòng xuống ~800-900 dòng, tăng mật độ thông tin kỹ thuật lên 100%.
5. **Nâng cấp công cụ Lint**: Cập nhật `tools/lint/check_documentation_system.py` để quét thêm thư mục `wiki/`, đảm bảo các liên kết `file:///...` trong Wiki được tự động bảo vệ chống gãy vỡ trong tương lai.