Add read-only production runtime audit

docs-legacy/diataxis-audit.md

@@ -0,0 +1,104 @@
+# Audit kiến trúc tài liệu theo Diataxis
+
+## Phân loại
+
+**Loại tài liệu:** Explanation kèm inventory.
+
+**Reader job:** hiểu bộ tài liệu được tổ chức thế nào và nên đọc gì cho từng
+mục tiêu.
+
+**Giả định:** code và cấu hình runtime là nguồn sự thật; tài liệu không được dùng
+để chứng minh một hành vi nếu code đã thay đổi.
+
+## Chẩn đoán
+
+Bộ tài liệu hiện tại mạnh về **Explanation** và **Reference**. Các trang `00–29`
+mô tả gần như toàn bộ kiến trúc, ingestion, RAG, API, vận hành và giới hạn. Tuy
+nhiên ba vấn đề làm người đọc khó sử dụng:
+
+1. Người mới không có tutorial ngắn dẫn qua một kết quả end-to-end.
+2. Nhiều trang trộn rationale, lệnh vận hành và bảng tra cứu.
+3. Tên file đánh số theo thành phần, chưa thể hiện reader job; người đọc phải
+   biết kiến trúc trước khi biết nên mở trang nào.
+
+## Kiến trúc mục tiêu
+
+| Reader job | Nhóm | Lời hứa |
+|---|---|---|
+| Học qua thực hành | `tutorials/` | Đi theo một đường an toàn để hiểu một lượt RAG |
+| Hoàn thành công việc | `how-to/` | Thực hiện setup, kiểm thử, ingestion, deploy hoặc điều tra |
+| Tra cứu chính xác | Các trang reference hiện hành | Tìm endpoint, config, schema, reason code và giới hạn |
+| Hiểu thiết kế | Các trang explanation hiện hành | Hiểu kiến trúc, trade-off và guardrail |
+
+Không di chuyển hàng loạt các file `00–29`, vì chúng đã có nhiều backlink từ
+code, ADR và runbook. Lớp Diataxis mới bổ sung điều hướng và các reader job còn
+thiếu; việc tách vật lý chỉ nên làm khi có redirect/link checker trong CI.
+
+## Phân loại bộ tài liệu hiện hành
+
+### Tutorial
+
+- `tutorials/first-grounded-query.md`
+
+### How-to
+
+- `how-to/rebuild-and-publish-corpus.md`
+- `how-to/run-tests-and-evals.md`
+- `how-to/deploy-and-rollback.md`
+- `how-to/trace-a-request.md`
+- `23-local-development.md`
+- `24-production-operations.md`
+- `25-troubleshooting.md`
+
+### Reference
+
+- `01-repository-structure.md`
+- `06-document-model-and-chunking.md`
+- `07-indexing-and-storage.md`
+- `12-api-architecture.md`
+- `14-data-stores.md`
+- `15-configuration.md`
+- `17-observability.md`
+- `18-testing.md`
+- `26-known-limitations.md`
+- `29-glossary.md`
+- `reference/documentation-catalog.md`
+
+### Explanation
+
+- `00-project-overview.md`
+- `02-system-architecture.md`
+- `03-data-flow.md`
+- `04-ingestion-pipeline.md` đến `11-generation-and-grounding.md`
+- `13-frontend-architecture.md`
+- `16-security.md`
+- `19-rag-evaluation.md`
+- `20-deployment.md` đến `22-ci-cd.md`
+- `27-technical-debt.md`, `28-roadmap-from-code.md`
+- `explanation/why-structured-rag.md`
+- `pipeline-tu-pdf-den-chatbot-production.md`
+
+Một số trang có nội dung phụ thuộc loại khác. Ví dụ `24-production-operations.md`
+là how-to chính nhưng chứa bảng incident reference; `pipeline-tu-pdf...` là
+explanation chính nhưng có lệnh tái hiện. Chúng được giữ vì đang phục vụ handoff
+kỹ thuật; các how-to mới trích riêng đường thao tác để người vận hành không phải
+đọc toàn bộ narrative.
+
+## Các thay đổi được áp dụng
+
+1. Thêm tutorial theo một query có citation.
+2. Thêm how-to riêng cho corpus, quality, deploy/rollback và tracing.
+3. Thêm catalog để tìm tài liệu theo reader job và vai trò.
+4. Thêm explanation ngắn cho mental model structured RAG.
+5. Cập nhật `docs/README.md` làm cổng vào theo Diataxis.
+6. Sửa các claim drift được xác minh trực tiếp từ code/workflow hiện tại.
+
+## Checklist duy trì
+
+- [ ] Mỗi trang mới có một reader job chính.
+- [ ] How-to có prerequisites, verification và recovery.
+- [ ] Reference ghi rõ default, limit và source-of-truth.
+- [ ] Explanation không giả làm hướng dẫn thao tác.
+- [ ] Số liệu có ngày hoặc artifact nguồn.
+- [ ] Link tương đối được kiểm tra trước commit.
+- [ ] Khi code và docs mâu thuẫn, sửa docs; không dùng docs cũ để phủ định code.