> ## Documentation Index
> Fetch the complete documentation index at: https://huongdan.luklak.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quy trình Vận hành Documentation Portal

> Giải thích toàn bộ cơ chế: từ AI Agent viết nội dung, đến CI/CD tự động đưa lên web — dành cho người không biết code.

## Tổng quan — Từ ý tưởng đến trang web

Hệ thống tài liệu Luklak hoạt động theo 5 bước tự động:

```mermaid theme={null}
graph LR
    User["Chat User"] -- "Mệnh lệnh" --> Agent["AI Agent Lulu"]
    Agent -- "Viết bài" --> Git["Git Repo Local"]
    Git -- "Push" --> GitHub["GitHub Remote"]
    GitHub -- "Webhook" --> Mintlify["Mintlify Build"]
    Mintlify -- "Public" --> Web["docs.luklak.com"]
```

<Steps>
  <Step title="Chat — Ra đề">
    Người phụ trách nội dung ra lệnh bằng ngôn ngữ tự nhiên qua cửa sổ chat, ví dụ: "Viết tiếp group Use & Operate."
  </Step>

  <Step title="AI Agent (Lulu) — Viết + Cấu hình">
    Agent **Lulu** (Luklak Learning Unit) đóng vai trò Tổng biên tập: đọc file nguồn tiếng Anh, transcreate sang tiếng Việt, tạo file `.mdx`, và cập nhật menu sidebar (`docs.json`).
  </Step>

  <Step title="Git Push — Đẩy lên kho">
    Agent tự chạy lệnh `git commit` + `git push` để gửi toàn bộ thay đổi lên GitHub.
  </Step>

  <Step title="Mintlify CI/CD — Tự động build">
    GitHub nhận code mới → kích hoạt Mintlify → hệ thống kiểm tra lỗi → build thành trang web.
  </Step>

  <Step title="Web Live — Cập nhật">
    Trang web tài liệu tự động cập nhật trong chưa đầy 2 phút. Không cần ai bấm nút deploy.
  </Step>
</Steps>

***

## Kiến trúc Dự án — Cái gì nằm ở đâu?

### Hai kho song song

<CardGroup cols={2}>
  <Card title="Kho EN (Gốc)" icon="file-lines" iconType="duotone">
    Tài liệu tiếng Anh chuẩn — "bản vẽ kỹ thuật" gốc. **Chỉ đọc**, không sửa.
  </Card>

  <Card title="Kho VN (Đích)" icon="pen-nib" iconType="duotone">
    Tài liệu tiếng Việt — nơi Agent tạo bài mới. Đây là kho được **deploy lên web**.
  </Card>
</CardGroup>

### Cấu trúc thư mục

```
mintlify-tailieuvn/
├── docs.json                    ← "Bản đồ" menu sidebar
├── images/                      ← Tất cả hình ảnh
├── 01-getting-started/          ← Tab 1: Bắt đầu
├── 02-platform/                 ← Tab 2: Nền tảng cốt lõi
│   ├── platform-overview/       ← Tổng quan + 9 Lego Blocks
│   ├── governance/              ← Tầng 1: Governance
│   ├── function-design/         ← Thiết kế Chức năng
│   └── use-and-operate/         ← Sử dụng & Vận hành
└── 03-build/                    ← Tab 3: Case Studies
```

### File `docs.json` — "Bộ não" của sidebar

<Info>
  File này quyết định **thứ tự hiển thị** trên menu. Nếu bạn viết 10 bài nhưng không khai báo trong `docs.json`, **không bài nào xuất hiện trên web**.
</Info>

Cấu trúc logic: `Tab → Group → Sub-group → Page`.

***

## Cơ chế AI Agent

### Agent là gì?

Agent (code name: **Antigravity**) không phải chatbot thông thường. Nó là một **AI có tay** — ngoài việc hiểu ngôn ngữ, nó còn thực hiện hành động trực tiếp trên máy tính:

<CardGroup cols={3}>
  <Card title="Đọc file" icon="book-open" iconType="duotone">
    Mở và đọc bất kỳ file nào trên máy — file nguồn EN, file cấu hình, ảnh.
  </Card>

  <Card title="Tạo & Sửa file" icon="file-pen" iconType="duotone">
    Viết bài `.mdx` mới hoặc cập nhật file đang có (menu, nội dung).
  </Card>

  <Card title="Chạy lệnh Terminal" icon="terminal" iconType="duotone">
    Tự commit code, push lên GitHub, copy ảnh — mọi thao tác dòng lệnh.
  </Card>
</CardGroup>

### Vòng lặp làm việc (Agent Loop)

Mỗi lần nhận lệnh, Agent chạy qua 6 bước:

<Steps>
  <Step title="AI Agent (Lulu) nhận lệnh từ Chat">
    Bạn nói: "Viết tiếp group Use & Operate."
  </Step>

  <Step title="Khảo sát nguồn">
    Agent tự vào thư mục EN, đếm file, loại trùng → kết luận: "Cần tạo 11 bài."
  </Step>

  <Step title="Đọc & Transcreate">
    Đọc từng file EN → **viết lại hoàn toàn** bằng tiếng Việt (không dịch word-by-word). Giữ đúng giọng văn kiến trúc B2B, thuật ngữ chuẩn Luklak.
  </Step>

  <Step title="Tạo file .mdx">
    Gọi tool `write_to_file` → 11 file `.mdx` mới xuất hiện trên máy tính.
  </Step>

  <Step title="Cập nhật menu">
    Gọi tool `replace_file_content` → thêm 11 bài vào `docs.json` ở đúng vị trí.
  </Step>

  <Step title="Commit + Push">
    Chạy `git add . → git commit → git push` → code lên GitHub.
  </Step>
</Steps>

### Ví dụ cụ thể: Viết group "Sử dụng & Vận hành"

| Bước          | Agent làm gì                                              | Kết quả                                                             |
| :------------ | :-------------------------------------------------------- | :------------------------------------------------------------------ |
| Khảo sát      | Đọc thư mục `mintlify-en/en/02-platform/use-and-operate/` | Phát hiện 13 file, loại 2 trùng → 11 bài cần viết                   |
| Đọc nguồn     | `view_file("personal-home.mdx")` — đọc 69 dòng EN         | Hiểu: "Personal Home = dashboard cá nhân"                           |
| Transcreate   | Viết lại hoàn toàn bằng tiếng Việt                        | "Trang chủ Cá nhân" — giọng kiến trúc, dùng "Đầu việc", "Mảng việc" |
| Tạo file      | `write_to_file("trang-chu.mdx")`                          | File mới trên máy                                                   |
| Cập nhật menu | Sửa `docs.json` — thêm group + 12 pages                   | Sidebar hiển thị đúng                                               |
| Push          | `git push origin main`                                    | Code lên GitHub trong 5 giây                                        |

### Skill — Tại sao Agent viết đúng giọng?

Agent được trang bị các **nguồn kiến thức** để đảm bảo nhất quán:

<CardGroup cols={2}>
  <Card title="Knowledge Items (KI)" icon="brain" iconType="duotone">
    Các file "kiến thức" lưu từ những cuộc chat trước. VD: "Luklak dùng giọng văn kiến trúc B2B", "Dùng từ 'Đầu việc' cho Object."
  </Card>

  <Card title="Conversation History" icon="clock-rotate-left" iconType="duotone">
    Agent nhớ các quyết định trước đó. VD: Bạn đã chọn giữ "kì diệu" và "kịch chân tường" trong bản Việt.
  </Card>

  <Card title="File EN gốc" icon="language" iconType="duotone">
    Nội dung chuẩn — Agent đọc để **hiểu ý nghĩa**, không phải để dịch máy móc.
  </Card>

  <Card title="docs.json hiện tại" icon="sitemap" iconType="duotone">
    Agent đọc cấu trúc menu để biết group mới nên đặt ở đâu — ngang hàng hay lồng vào.
  </Card>
</CardGroup>

### Feedback Loop — Bạn kiểm duyệt, Agent sửa

<Steps>
  <Step title="Agent viết bản đầu">
    Tạo file, push lên web.
  </Step>

  <Step title="Bạn review trên web">
    Kiểm tra nội dung, cấu trúc menu, vị trí bài.
  </Step>

  <Step title="Feedback qua Chat">
    VD: "Thiết kế Chức năng đang lồng trong 9 Lego Blocks, phải tách ra ngang hàng."
  </Step>

  <Step title="Agent sửa + push lại">
    Hiểu yêu cầu → sửa `docs.json` → push → sidebar cập nhật đúng cấu trúc.
  </Step>
</Steps>

<Tip>
  Vòng lặp này có thể chạy **không giới hạn** cho đến khi nội dung đúng ý. Mỗi vòng mất khoảng 1-3 phút.
</Tip>

***

## CI/CD Pipeline — Từ Push đến Web

### CI/CD là gì?

<CardGroup cols={2}>
  <Card title="CI — Continuous Integration" icon="magnifying-glass-chart" iconType="duotone">
    Mỗi lần có thay đổi, hệ thống tự động **kiểm tra** xem có lỗi cú pháp, file thiếu, hay link hỏng không.
  </Card>

  <Card title="CD — Continuous Deployment" icon="rocket" iconType="duotone">
    Nếu không có lỗi, hệ thống tự động **đưa lên web** — không cần ai bấm nút "deploy".
  </Card>
</CardGroup>

### Luồng chi tiết

```mermaid theme={null}
graph TD
    A["Push code"] --> B{"Check Syntax"}
    B -- "Lỗi" --> C["❌ Thông báo cho User"]
    B -- "Hợp lệ" --> D["🏗️ Build MDX sang HTML"]
    D --> E["📦 Phân phối lên CDN"]
    E --> F["✅ Live trên Web"]
```

<Steps>
  <Step title="Agent push code lên GitHub">
    Lệnh `git push origin main` gửi toàn bộ file mới/sửa lên kho.
  </Step>

  <Step title="GitHub kích hoạt Mintlify webhook">
    GitHub tự động gửi tín hiệu "có code mới" cho Mintlify.
  </Step>

  <Step title="Mintlify đọc & kiểm tra">
    Hệ thống đọc `docs.json` + tất cả file `.mdx`, kiểm tra cú pháp và liên kết.
  </Step>

  <Step title="Build thành trang web">
    Chuyển đổi Markdown thành HTML với giao diện đẹp, responsive, có search.
  </Step>

  <Step title="Deploy lên CDN toàn cầu">
    Nội dung được phân phối qua mạng lưới CDN — truy cập nhanh từ mọi nơi.
  </Step>
</Steps>

### Thời gian thực tế

| Bước                                   | Thời gian     |
| :------------------------------------- | :------------ |
| Agent viết 11 bài + cập nhật menu      | \~3 phút      |
| `git push`                             | \~5 giây      |
| Mintlify build + deploy                | \~30-60 giây  |
| **Tổng: từ "viết xong" đến "lên web"** | **\< 2 phút** |

***

## Ai làm gì?

| Vai trò                  | Công việc                                                          | Công cụ                                                                    |
| :----------------------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------- |
| **Bạn (Specifier)**      | Ra đề, review, quyết định giọng văn & cấu trúc                     | Chat window                                                                |
| **Agent (Builder)**      | Đọc nguồn EN, transcreate VN, tạo file, cập nhật menu, push code   | Tools: `view_file`, `write_to_file`, `replace_file_content`, `run_command` |
| **GitHub (Storage)**     | Lưu trữ toàn bộ lịch sử thay đổi, cho phép rollback bất kỳ lúc nào | Git version control                                                        |
| **Mintlify (Publisher)** | Tự động build HTML từ Markdown, deploy lên web                     | CI/CD pipeline                                                             |

<Info>
  **Kết quả:** Bạn không cần biết code, không cần cấu hình server, không cần copy-paste. Bạn chỉ cần **nói rõ ý muốn** — hệ thống Agent Lulu + CI/CD sẽ biến ý tưởng thành trang web tài liệu chuyên nghiệp trong vài phút.

  Xem thêm: [Setup & Bản sắc Lulu Agent](/04-ops/lulu-agent-setup)
</Info>