diff --git a/docs/vi-vn/404.md b/docs/vi-vn/404.md
new file mode 100644
index 0000000..7790b1e
--- /dev/null
+++ b/docs/vi-vn/404.md
@@ -0,0 +1,20 @@
+---
+title: Không tìm thấy trang
+description: Trang bạn đang tìm không tồn tại
+template: splash
+---
+
+# Không tìm thấy trang
+
+Trang bạn đang tìm không tồn tại.
+
+## Bạn có thể làm gì?
+
+- Kiểm tra lại URL xem có bị gõ sai không
+- Quay về [trang chủ](/vi-vn/)
+- Duyệt [tài liệu](/vi-vn/tutorials/tea-lite-quickstart)
+- Tìm kiếm nội dung cần thiết bằng thanh search ở phía trên
+
+## Cần hỗ trợ?
+
+Nếu bạn cho rằng trang này đáng ra phải tồn tại, hãy [tạo issue](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/issues) trên GitHub.
diff --git a/docs/vi-vn/explanation/engagement-models.md b/docs/vi-vn/explanation/engagement-models.md
new file mode 100644
index 0000000..5b673dd
--- /dev/null
+++ b/docs/vi-vn/explanation/engagement-models.md
@@ -0,0 +1,345 @@
+---
+title: 'Giải thích các mô hình engagement của TEA'
+description: Hiểu 5 cách dùng TEA, từ standalone tới tích hợp đầy đủ với BMad Method
+---
+
+# Giải thích các mô hình engagement của TEA
+
+TEA là tùy chọn và linh hoạt. Có **5 cách hợp lệ** để dùng TEA, và bạn nên chọn có chủ đích dựa trên bối cảnh dự án thay vì mặc định áp một mô hình cho mọi nơi.
+
+## Tổng quan
+
+**TEA không bắt buộc.** Hãy chọn mô hình phù hợp với thực tế dự án:
+
+1. **No TEA** - bỏ qua toàn bộ workflow của TEA
+2. **TEA Solo** - dùng TEA độc lập, không cần full BMad Method
+3. **TEA Lite** - lối vào cho người mới, chủ yếu dùng `automate`
+4. **TEA Integrated (Greenfield)** - tích hợp TEA trọn vẹn cho dự án mới
+5. **TEA Integrated (Brownfield)** - tích hợp TEA trên codebase hiện có
+
+## Vấn đề
+
+### Cách tiếp cận one-size-fits-all không hiệu quả
+
+Các công cụ testing truyền thống thường ép một cách dùng duy nhất:
+
+- Phải dùng cả framework
+- Áp dụng kiểu all-or-nothing
+- Không linh hoạt theo loại dự án
+- Nếu không khớp thực tế, team bỏ luôn công cụ
+
+TEA đi theo hướng khác:
+
+- Dự án khác nhau có nhu cầu khác nhau
+- Độ trưởng thành của team khác nhau
+- Bối cảnh greenfield và brownfield không giống nhau
+- Tăng tính linh hoạt giúp tăng khả năng adoption
+
+## Năm mô hình engagement
+
+### Mô hình 1: No TEA
+
+**Là gì:** bỏ qua mọi workflow TEA, tiếp tục cách testing hiện tại.
+
+**Khi nào nên dùng:**
+
+- Team đã có thực hành testing rất ổn định
+- Chất lượng hiện tại đã cao
+- Toolchain đang dùng đã giải quyết tốt vấn đề
+- TEA không tạo thêm giá trị đáng kể
+
+**Những gì bạn bỏ lỡ:**
+
+- Lập kế hoạch test theo rủi ro
+- Review test có hệ thống
+- Gate decision có bằng chứng
+- Pattern thống nhất từ knowledge base
+
+**Những gì bạn giữ được:**
+
+- Toàn quyền kiểm soát
+- Tool hiện có
+- Chuyên môn nội bộ
+- Không có learning curve mới
+
+**Ví dụ:**
+
+```text
+Team của bạn:
+- QA team dày kinh nghiệm
+- Test practice đã thành chuẩn nội bộ
+- Suite chất lượng cao
+- Không có pain point rõ ràng
+
+Quyết định: không dùng TEA
+```
+
+**Kết luận:** đây là một lựa chọn hoàn toàn hợp lệ nếu hệ hiện tại đang vận hành tốt.
+
+---
+
+### Mô hình 2: TEA Solo
+
+**Là gì:** dùng workflow TEA độc lập mà không cần full BMad Method.
+
+**Khi nào nên dùng:**
+
+- Dự án không theo BMad
+- Chỉ muốn mô hình vận hành chất lượng của TEA
+- Không cần toàn bộ planning workflow của BMad
+- Có thể tự cung cấp requirements, spec hoặc source tree phân tích được
+
+**Trình tự điển hình:**
+
+```text
+1. test-design
+2. atdd hoặc automate
+3. test-review (tùy chọn)
+4. trace
+```
+
+**Bạn cần tự mang theo:**
+
+- coverage oracle hoặc tài liệu yêu cầu
+- môi trường phát triển và hệ thống chạy test
+- context dự án
+
+**TEA cung cấp:**
+
+- test planning theo rủi ro
+- sinh test
+- review chất lượng
+- traceability và gate decision
+
+**Tùy chọn thêm:**
+
+- `framework` nếu muốn scaffold test harness
+- `ci` nếu muốn sinh pipeline CI/CD
+
+**Ví dụ:**
+
+```text
+Bạn đang dùng Scrum, quản lý story bằng Jira, không chạy theo BMad.
+
+Luồng làm việc:
+1. Export story từ Jira
+2. Chạy test-design cho epic
+3. Chạy atdd cho từng story
+4. DEV implement
+5. Chạy trace để xem độ phủ và gate
+```
+
+**Kết luận:** phù hợp với team muốn lấy lợi ích của TEA mà không cần cam kết toàn bộ phương pháp BMad.
+
+---
+
+### Mô hình 3: TEA Lite
+
+**Là gì:** cách vào đơn giản nhất cho người mới, chủ yếu dùng `automate` để test feature đã tồn tại.
+
+**Khi nào nên dùng:**
+
+- Đang học nền tảng TEA
+- Muốn thấy kết quả nhanh
+- Đang test ứng dụng sẵn có
+- Chưa có thời gian đi full methodology
+
+**Workflow điển hình:**
+
+```text
+1. framework
+2. test-design (tùy chọn)
+3. automate
+4. chạy test, test pass ngay
+```
+
+**Ví dụ:**
+
+```text
+Developer mới:
+- Chưa từng dùng TEA
+- Muốn thêm test cho app hiện có
+- Chỉ có khoảng 30 phút
+
+Các bước:
+1. Chạy framework
+2. Chạy automate trên một feature/demo
+3. Có test được sinh ra và chạy pass
+4. Nắm được các khái niệm TEA cơ bản
+```
+
+**Bạn nhận được:**
+
+- Một test framework hoạt động được
+- Test pass cho feature hiện có
+- Trải nghiệm học nhanh
+- Nền tảng để mở rộng dần
+
+**Những gì còn thiếu:**
+
+- Luồng TDD kiểu `atdd`
+- Risk-based planning sâu
+- Gate decision hoàn chỉnh của `trace`
+- Toàn bộ capability của TEA
+
+**Kết luận:** đây là điểm khởi đầu rất hợp lý cho người mới.
+
+---
+
+### Mô hình 4: TEA Integrated (Greenfield)
+
+**Là gì:** tích hợp đầy đủ TEA vào các pha của BMad Method cho dự án mới.
+
+**Khi nào nên dùng:**
+
+- Dự án mới bắt đầu từ đầu
+- Đang dùng BMad Method hoặc Enterprise track
+- Muốn có quality operating model trọn vẹn
+- Testing ảnh hưởng trực tiếp đến thành công dự án
+
+**Lifecycle điển hình:**
+
+**Phase 2: Planning**
+
+- PM tạo PRD với FR và NFR
+- Có thể chạy `nfr-assess` nếu cần
+
+**Phase 3: Solutioning**
+
+- Architect tạo architecture
+- TEA chạy `test-design` ở mức hệ thống
+- TEA chạy `framework`
+- TEA chạy `ci`
+- Kiểm tra implementation-readiness
+
+**Phase 4: Implementation theo từng epic**
+
+- SM chạy `sprint-planning`
+- TEA chạy `test-design` cho epic hiện tại
+- SM tạo stories
+- Có thể chạy `atdd` trước khi dev
+- DEV implement
+- TEA chạy `automate`
+- Có thể chạy `test-review`
+- TEA chạy `trace` Phase 1 để cập nhật coverage
+
+**Release gate**
+
+- Có thể chạy `test-review` lần cuối
+- Có thể chạy `nfr-assess`
+- Chạy `trace` Phase 2 để ra quyết định `PASS / CONCERNS / FAIL / WAIVED`
+
+**Bạn nhận được:**
+
+- mô hình chất lượng đầy đủ
+- planning có ưu tiên theo rủi ro
+- pattern nhất quán giữa các epic
+- gate decision dựa trên bằng chứng
+
+**Kết luận:** đây là cách dùng đầy đủ và mạnh nhất, phù hợp team có quy trình bài bản.
+
+---
+
+### Mô hình 5: TEA Integrated (Brownfield)
+
+**Là gì:** tích hợp TEA vào codebase sẵn có, tập trung vào regression risk và integration risk.
+
+**Khi nào nên dùng:**
+
+- Có codebase cũ hoặc đang vận hành
+- Cần giữ regression dưới kiểm soát
+- Có nhiều phụ thuộc, nhiều module cũ mới đan xen
+- Muốn tăng dần chất lượng thay vì làm lại từ đầu
+
+**Lifecycle điển hình:**
+
+**Documentation / baseline**
+
+- Có thể cần `document-project` nếu dự án thiếu tài liệu
+- Chạy `trace` sớm để lấy baseline coverage hiện có
+
+**Phase 3: Solutioning**
+
+- system-level `test-design`
+- `framework`
+- `ci`
+
+**Phase 4: Per epic**
+
+- `test-design` tập trung hotspot và regression
+- có thể chạy `atdd`
+- `automate`
+- `test-review`
+- `trace`
+
+**Release gate**
+
+- `trace` Phase 2
+- `nfr-assess` nếu chưa chạy trước đó
+
+**Khác biệt lớn so với greenfield:**
+
+- Tập trung vào vùng rủi ro do code cũ
+- Cần baseline trước khi mở rộng coverage
+- Test design phải tính đến integration seam và side effect
+
+**Kết luận:** đây là mô hình phù hợp nhất khi mục tiêu là cải thiện chất lượng trên hệ thống đang sống.
+
+---
+
+## Cách chọn mô hình phù hợp
+
+### Chọn `No TEA` nếu
+
+- hệ hiện tại đã rất hiệu quả
+- không có pain point thật sự về test
+- team không cần thêm structure mới
+
+### Chọn `TEA Solo` nếu
+
+- muốn dùng TEA ngoài BMad
+- đã có tài liệu yêu cầu riêng
+- cần planning và review tốt hơn nhưng không muốn đổi methodology tổng
+
+### Chọn `TEA Lite` nếu
+
+- đang học
+- cần kết quả nhanh
+- muốn có test pass sớm cho feature hiện có
+
+### Chọn `Integrated Greenfield` nếu
+
+- dự án mới
+- cần quality gate rõ ràng
+- muốn đưa testability vào từ đầu
+
+### Chọn `Integrated Brownfield` nếu
+
+- đang nâng cấp hệ thống hiện có
+- sợ regression
+- cần quản trị coverage và release gate có bằng chứng
+
+## Điều này quan trọng thế nào với QC
+
+Với QC, engagement model quyết định:
+
+- mức độ TEA can thiệp vào quy trình hằng ngày
+- độ sâu của planning và review
+- cách team dùng test như artifact kỹ thuật hay chỉ như output cuối cùng
+- khối lượng bằng chứng cần chuẩn bị cho gate và release
+
+## Tài liệu liên quan
+
+- [TEA overview](/docs/vi-vn/explanation/tea-overview.md)
+- [Risk-based testing](/docs/vi-vn/explanation/risk-based-testing.md)
+- [Cách chạy test-design](/docs/vi-vn/how-to/workflows/run-test-design.md)
+- [Cách chạy automate](/docs/vi-vn/how-to/workflows/run-automate.md)
+- [Cách chạy trace](/docs/vi-vn/how-to/workflows/run-trace.md)
+
+## Kết luận
+
+Giá trị của TEA không chỉ nằm ở số workflow nó có, mà ở chỗ bạn có thể dùng nó theo đúng độ chín của team và đúng mức độ kiểm soát mà dự án cần.
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/explanation/fixture-architecture.md b/docs/vi-vn/explanation/fixture-architecture.md
new file mode 100644
index 0000000..8500485
--- /dev/null
+++ b/docs/vi-vn/explanation/fixture-architecture.md
@@ -0,0 +1,383 @@
+---
+title: 'Giải thích kiến trúc fixture'
+description: Hiểu pattern pure function → fixture → composition của TEA cho test utility có thể tái sử dụng
+---
+
+# Giải thích kiến trúc fixture
+
+Kiến trúc fixture là pattern của TEA để xây dựng các test utility có thể tái sử dụng, kiểm thử được và dễ composition. Nguyên lý cốt lõi là: **viết pure function trước, rồi mới bọc bằng fixture của framework**.
+
+## Tổng quan
+
+**Pattern gồm 4 bước:**
+
+1. Viết utility như một pure function
+2. Bọc nó trong fixture của framework như Playwright hoặc Cypress
+3. Compose nhiều fixture bằng `mergeTests`
+4. Đóng gói để tái sử dụng giữa các dự án
+
+### Luồng kiến trúc fixture
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'14px'}}}%%
+flowchart TD
+ Start([Testing Need]) --> Pure[Step 1: Pure Function
helpers/api-request.ts]
+ Pure --> Fixture[Step 2: Fixture Wrapper
fixtures/api-request.ts]
+ Fixture --> Compose[Step 3: Composition
fixtures/index.ts]
+ Compose --> Use[Step 4: Use in Tests
tests/**.spec.ts]
+```
+
+**Lợi ích ở từng bước:**
+
+1. **Pure function:** dễ unit test, portable
+2. **Fixture wrapper:** tích hợp framework, API sạch
+3. **Composition:** kết hợp nhiều capability
+4. **Usage:** import gọn, type-safe
+
+## Vấn đề
+
+### Framework-first là anti-pattern phổ biến
+
+```typescript
+export const test = base.extend({
+ apiRequest: async ({ request }, use) => {
+ await use(async (options) => {
+ const response = await request.fetch(options.url, {
+ method: options.method,
+ data: options.data,
+ });
+
+ if (!response.ok()) {
+ throw new Error(`API request failed: ${response.status()}`);
+ }
+
+ return response.json();
+ });
+ },
+});
+```
+
+**Các vấn đề:**
+
+- Không unit test được nếu không có Playwright context
+- Bị khóa vào framework
+- Khó compose với utility khác
+- Khó mock để test chính utility đó
+
+### Copy-paste utility giữa các test
+
+```typescript
+test('test 1', async ({ request }) => {
+ const response = await request.post('/api/users', { data: {...} });
+ const body = await response.json();
+ if (!response.ok()) throw new Error('Failed');
+});
+
+test('test 2', async ({ request }) => {
+ const response = await request.post('/api/users', { data: {...} });
+ const body = await response.json();
+ if (!response.ok()) throw new Error('Failed');
+});
+```
+
+Vấn đề là duplication, xử lý lỗi không đồng nhất và rất khó cập nhật hàng loạt.
+
+## Lời giải: pattern 3 bước
+
+### Bước 1: pure function
+
+```typescript
+// helpers/api-request.ts
+export async function apiRequest({ request, method, url, data, headers = {} }: ApiRequestParams): Promise {
+ const response = await request.fetch(url, {
+ method,
+ data,
+ headers,
+ });
+
+ if (!response.ok()) {
+ throw new Error(`API request failed: ${response.status()}`);
+ }
+
+ return {
+ status: response.status(),
+ body: await response.json(),
+ };
+}
+```
+
+**Vì sao nên bắt đầu từ pure function:**
+
+- Có thể unit test bằng mock dependency
+- Không phụ thuộc framework cụ thể
+- Dễ suy luận hành vi
+- Có thể dùng lại trong script, CLI hoặc môi trường khác
+
+Ví dụ unit test:
+
+```typescript
+describe('apiRequest', () => {
+ it('should throw on non-OK response', async () => {
+ const mockRequest = {
+ fetch: vi.fn().mockResolvedValue({ ok: () => false, status: () => 500 }),
+ };
+
+ await expect(
+ apiRequest({
+ request: mockRequest,
+ method: 'GET',
+ url: '/api/test',
+ }),
+ ).rejects.toThrow('API request failed: 500');
+ });
+});
+```
+
+### Bước 2: fixture wrapper
+
+```typescript
+// fixtures/api-request.ts
+import { test as base } from '@playwright/test';
+import { apiRequest as apiRequestFn } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequestFn }>({
+ apiRequest: async ({ request }, use) => {
+ await use((params) => apiRequestFn({ request, ...params }));
+ },
+});
+
+export { expect } from '@playwright/test';
+```
+
+**Lợi ích:**
+
+- Fixture cung cấp context framework
+- Logic vẫn ở pure function
+- Tách bạch concern rõ ràng
+- Có thể thay framework mà không phải viết lại core logic
+
+### Bước 3: composition với `mergeTests`
+
+```typescript
+// fixtures/index.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestTest } from './api-request';
+import { test as authSessionTest } from './auth-session';
+import { test as logTest } from './log';
+
+export const test = mergeTests(apiRequestTest, authSessionTest, logTest);
+export { expect } from '@playwright/test';
+```
+
+**Cách dùng:**
+
+```typescript
+import { test, expect } from '../support/fixtures';
+
+test('should update profile', async ({ apiRequest, authToken, log }) => {
+ log.info('Starting profile update test');
+
+ const { status, body } = await apiRequest({
+ method: 'PATCH',
+ url: '/api/profile',
+ data: { name: 'New Name' },
+ headers: { Authorization: `Bearer ${authToken}` },
+ });
+
+ expect(status).toBe(200);
+ expect(body.name).toBe('New Name');
+});
+```
+
+Lưu ý: ví dụ trên dùng signature kiểu vanilla (`url`, `data`). Playwright Utils dùng tên tham số hơi khác như `path`, `body`.
+
+## TEA áp dụng pattern này ra sao
+
+Khi chạy `framework` với `tea_use_playwright_utils: true`, TEA scaffold cấu trúc gần giống:
+
+```text
+tests/
+├── support/
+│ ├── helpers/
+│ │ ├── api-request.ts
+│ │ └── auth-session.ts
+│ └── fixtures/
+│ ├── api-request.ts
+│ ├── auth-session.ts
+│ └── index.ts
+└── e2e/
+ └── example.spec.ts
+```
+
+Khi chạy `test-review`, TEA cũng kiểm tra:
+
+- utility có phải pure function không
+- fixture có chỉ là wrapper mỏng không
+- có dùng composition đúng cách không
+- utility có thể unit test được không
+
+## Pattern export package
+
+### Tái sử dụng fixture giữa nhiều dự án
+
+**Cách 1: tự build package nội bộ**
+
+```json
+{
+ "name": "@company/test-utils",
+ "exports": {
+ "./api-request": "./fixtures/api-request.ts",
+ "./auth-session": "./fixtures/auth-session.ts",
+ "./log": "./fixtures/log.ts"
+ }
+}
+```
+
+**Cách dùng:**
+
+```typescript
+import { test as apiTest } from '@company/test-utils/api-request';
+import { test as authTest } from '@company/test-utils/auth-session';
+import { mergeTests } from '@playwright/test';
+
+export const test = mergeTests(apiTest, authTest);
+```
+
+**Cách 2: dùng Playwright Utils, thường là khuyến nghị tốt hơn**
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+```typescript
+import { test as base } from '@playwright/test';
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { createAuthFixtures } from '@seontechnologies/playwright-utils/auth-session';
+
+const authFixtureTest = base.extend(createAuthFixtures());
+export const test = mergeTests(apiRequestFixture, authFixtureTest);
+```
+
+**Vì sao Playwright Utils đáng cân nhắc:**
+
+- Đã được xây sẵn, test và bảo trì
+- Pattern thống nhất giữa nhiều dự án
+- Có nhiều utility sẵn như API, auth, network, logging, files
+- Có tài liệu và cộng đồng hỗ trợ
+
+**Khi nào nên tự xây:**
+
+- Có pattern đặc thù công ty
+- Hệ thống auth rất riêng
+- Có yêu cầu không nằm trong bộ utility sẵn có
+
+## So sánh pattern tốt và xấu
+
+### Anti-pattern: god fixture
+
+```typescript
+export const test = base.extend({
+ testUtils: async ({ page, request, context }, use) => {
+ await use({
+ apiRequest: async (...) => { },
+ login: async (...) => { },
+ createUser: async (...) => { },
+ deleteUser: async (...) => { },
+ uploadFile: async (...) => { },
+ // ... thêm rất nhiều method
+ });
+ }
+});
+```
+
+**Vấn đề:**
+
+- Không test riêng từng utility được
+- Không compose chọn lọc được
+- Không tái dùng từng phần được
+- File phình to, khó bảo trì
+
+### Pattern tốt: một concern cho mỗi fixture
+
+```typescript
+export const test = base.extend({ apiRequest });
+export const test = base.extend({ authSession });
+export const test = base.extend({ log });
+```
+
+Rồi compose:
+
+```typescript
+import { mergeTests } from '@playwright/test';
+export const test = mergeTests(apiRequestTest, authSessionTest, logTest);
+```
+
+## Khi nào nên dùng pattern này
+
+### Nên dùng cho
+
+**Reusable utilities:**
+
+- API request helper
+- Authentication handler
+- File operation helper
+- Network mocking helper
+
+**Test infrastructure:**
+
+- Shared fixture giữa nhiều team
+- Utility đóng gói thành package
+- Chuẩn test dùng cho toàn công ty
+
+### Có thể bỏ qua cho
+
+**One-off setup rất đơn giản:**
+
+```typescript
+test.beforeEach(async ({ page }) => {
+ await page.goto('/');
+ await page.click('#accept-cookies');
+});
+```
+
+**Helper chỉ dùng trong đúng một file test:**
+
+```typescript
+function createTestUser(name: string) {
+ return { name, email: `${name}@test.com` };
+}
+```
+
+## Điều này quan trọng thế nào với QC
+
+Kiến trúc fixture tốt giúp đội QC:
+
+- tái dùng thao tác chung mà không copy-paste
+- giảm chi phí bảo trì khi API hoặc auth thay đổi
+- giữ test gọn, dễ đọc và dễ review
+- tách rõ đâu là business assertion, đâu là kỹ thuật nền
+
+## Tài liệu liên quan
+
+- [Test quality standards](/docs/vi-vn/explanation/test-quality-standards.md)
+- [Knowledge base system](/docs/vi-vn/explanation/knowledge-base-system.md)
+- [Network-first patterns](/docs/vi-vn/explanation/network-first-patterns.md)
+- [Cách thiết lập test framework](/docs/vi-vn/how-to/workflows/setup-test-framework.md)
+- [Tích hợp Playwright Utils](/docs/vi-vn/how-to/customization/integrate-playwright-utils.md)
+- [Cách chạy automate](/docs/vi-vn/how-to/workflows/run-automate.md)
+
+## Kết luận
+
+Pattern `pure function → fixture → composition` giúp test utility:
+
+- dễ test
+- dễ tái dùng
+- dễ đóng gói
+- ít phụ thuộc framework hơn
+
+Đó là nền tảng rất quan trọng nếu muốn suite lớn lên mà vẫn kiểm soát được chất lượng.
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/explanation/knowledge-base-system.md b/docs/vi-vn/explanation/knowledge-base-system.md
new file mode 100644
index 0000000..9bf8501
--- /dev/null
+++ b/docs/vi-vn/explanation/knowledge-base-system.md
@@ -0,0 +1,411 @@
+---
+title: 'Giải thích hệ thống knowledge base'
+description: Hiểu cách TEA dùng tea-index.csv cho context engineering và chất lượng test nhất quán
+---
+
+# Giải thích hệ thống knowledge base
+
+Knowledge base của TEA là cách context engineering vận hành trong thực tế: hệ thống tự động nạp các chuẩn chuyên biệt vào ngữ cảnh AI để chất lượng test giữ ổn định, bất kể prompt thay đổi ra sao.
+
+## Tổng quan
+
+**Bài toán:** AI không có context sẽ cho đầu ra thất thường.
+
+**Cách truyền thống:**
+
+```text
+User: "Write tests for login"
+AI: [Sinh test với chất lượng ngẫu nhiên]
+- Lúc thì dùng hard wait
+- Lúc thì dùng pattern tốt
+- Không nhất quán giữa các session
+- Chất lượng phụ thuộc prompt
+```
+
+**TEA với knowledge base:**
+
+```text
+User: "Write tests for login"
+TEA: [Load test-quality.md, network-first.md, auth-session.md]
+TEA: [Sinh test theo pattern đã thiết lập]
+- Luôn dùng network-first khi phù hợp
+- Luôn dùng fixture đúng cách
+- Ổn định qua các session
+- Bớt phụ thuộc vào prompt wording
+```
+
+Kết quả là chất lượng mang tính hệ thống, không phải may rủi.
+
+## Vấn đề
+
+### Prompt-driven testing dẫn đến thiếu nhất quán
+
+**Session 1:**
+
+```text
+User: "Write tests for profile editing"
+AI: [Không có context hệ thống]
+await page.waitForTimeout(3000);
+```
+
+**Session 2:**
+
+```text
+User: "Write comprehensive tests for profile editing with best practices"
+AI: [Vẫn không có context chuẩn]
+await page.waitForSelector('.success', { timeout: 10000 });
+```
+
+**Session 3:**
+
+```text
+User: "Write tests using network-first patterns and proper fixtures"
+AI: [Prompt tốt hơn nhưng vẫn phải tự phát minh lại pattern]
+```
+
+Vấn đề là chất lượng phụ thuộc khả năng prompt engineering của từng người.
+
+### Knowledge drift
+
+Nếu không có knowledge base:
+
+- Team A dùng pattern X
+- Team B dùng pattern Y
+- Cả hai đều chạy được nhưng không thống nhất
+- Không có single source of truth
+- Pattern trôi dần theo thời gian
+
+## Lời giải: manifest `tea-index.csv`
+
+### Cách hoạt động
+
+**1. Manifest định nghĩa fragment**
+
+`src/agents/bmad-tea/resources/tea-index.csv`:
+
+```csv
+id,name,description,tags,tier,fragment_file
+test-quality,Test Quality,Execution limits and isolation rules,"quality,standards",knowledge/test-quality.md
+network-first,Network-First Safeguards,Intercept-before-navigate workflow,"network,stability",knowledge/network-first.md
+fixture-architecture,Fixture Architecture,Composable fixture patterns,"fixtures,architecture",knowledge/fixture-architecture.md
+```
+
+**2. Workflow nạp các fragment phù hợp**
+
+Khi người dùng chạy `atdd`:
+
+```text
+TEA đọc tea-index.csv
+Xác định fragment cần cho ATDD:
+- test-quality.md
+- network-first.md
+- component-tdd.md
+- fixture-architecture.md
+- data-factories.md
+
+Chỉ nạp 5 fragment này, không nạp toàn bộ 42 fragment
+```
+
+**3. Đầu ra ổn định**
+
+Mỗi lần `atdd` chạy:
+
+- cùng fragment được nạp
+- cùng pattern được áp dụng
+- cùng chuẩn chất lượng
+- cấu trúc test ổn định
+
+### Sơ đồ tải knowledge base
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'14px'}}}%%
+flowchart TD
+ User([User: atdd]) --> Workflow[TEA Workflow
Triggered]
+ Workflow --> Read[Read Manifest
tea-index.csv]
+
+ Read --> Identify{Identify Relevant
Fragments for ATDD}
+
+ Identify -->|Needed| L1[✓ test-quality.md]
+ Identify -->|Needed| L2[✓ network-first.md]
+ Identify -->|Needed| L3[✓ component-tdd.md]
+ Identify -->|Needed| L4[✓ data-factories.md]
+ Identify -->|Needed| L5[✓ fixture-architecture.md]
+
+ Identify -.->|Skip| S1[✗ contract-testing.md]
+ Identify -.->|Skip| S2[✗ burn-in.md]
+ Identify -.->|Skip| S3[+ 26 other fragments]
+
+ L1 --> Context[AI Context
5 fragments loaded]
+ L2 --> Context
+ L3 --> Context
+ L4 --> Context
+ L5 --> Context
+
+ Context --> Gen[Generate Tests
Following patterns]
+ Gen --> Out([Consistent Output
Same quality every time])
+```
+
+## Cấu trúc của một fragment
+
+Mỗi fragment thường đi theo khuôn này:
+
+````markdown
+# Fragment Name
+
+## Principle
+
+[Một câu mô tả pattern]
+
+## Rationale
+
+[Vì sao dùng pattern này]
+
+## Pattern Examples
+
+### Example 1
+
+```code
+[Ví dụ chạy được]
+```
+
+## Anti-Patterns
+
+### Don't Do This
+
+```code
+[Ví dụ xấu]
+```
+````
+
+### Ví dụ fragment `test-quality.md`
+
+````markdown
+# Test Quality
+
+## Principle
+
+Tests must be deterministic, isolated, explicit, focused, and fast.
+
+## Pattern Examples
+
+### Example 1: Deterministic Test
+
+```typescript
+const promise = page.waitForResponse(matcher);
+await page.click('button');
+await promise;
+```
+````
+
+````
+
+## TEA dùng knowledge base như thế nào
+
+### Nạp fragment theo từng workflow
+
+| Workflow | Fragment được nạp | Mục đích |
+| --- | --- | --- |
+| `framework` | `fixture-architecture`, `playwright-config`, `fixtures-composition` | Pattern hạ tầng |
+| `test-design` | `test-quality`, `test-priorities-matrix`, `risk-governance` | Chuẩn cho lập kế hoạch |
+| `atdd` | `test-quality`, `component-tdd`, `network-first`, `data-factories` | Pattern TDD |
+| `automate` | `test-quality`, `test-levels-framework`, `selector-resilience` | Sinh test toàn diện |
+| `test-review` | Toàn bộ fragment về chất lượng, resilience, debugging | Audit đầy đủ |
+| `ci` | `ci-burn-in`, `burn-in`, `selective-testing` | Tối ưu CI/CD |
+
+**Lợi ích:** chỉ nạp thứ cần dùng, không làm phình context.
+
+### Chọn fragment động
+
+TEA không nạp toàn bộ 42 fragment cùng lúc:
+
+```text
+User runs: atdd for authentication feature
+
+TEA analyzes context:
+- Feature type: Authentication
+- Relevant fragments:
+ - test-quality.md
+ - auth-session.md
+ - network-first.md
+ - email-auth.md
+ - data-factories.md
+
+Skips unrelated fragments
+````
+
+Kết quả là context gọn hơn, token ít hơn và chất lượng đầu ra tốt hơn.
+
+## Context engineering trong thực tế
+
+### Ví dụ: sinh test nhất quán
+
+**Không có knowledge base:**
+
+```text
+Session 1:
+test('api test', async ({ request }) => {
+ const response = await request.get('/api/users');
+ await page.waitForTimeout(2000);
+});
+
+Session 2:
+test('api test', async ({ request }) => {
+ const response = await request.get('/api/users');
+ const users = await response.json();
+});
+```
+
+Mỗi lần chạy sinh ra pattern khác nhau.
+
+**Có knowledge base và Playwright Utils:**
+
+```text
+TEA loads test-quality.md, network-first.md, api-request.md
+
+Generated:
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch users', async ({ apiRequest }) => {
+ const { status, body } = await apiRequest({
+ method: 'GET',
+ path: '/api/users'
+ }).validateSchema(UsersSchema);
+
+ expect(status).toBe(200);
+ expect(body).toBeInstanceOf(Array);
+});
+```
+
+Khác biệt chính:
+
+- Không có KB: pattern ngẫu nhiên
+- Có KB: luôn dùng utility và chuẩn giống nhau
+
+### Ví dụ: test-review nhất quán
+
+Không có knowledge base, cùng một suite có thể được nhận xét khác nhau giữa hai session. Có knowledge base, `test-review` sẽ dựa trên cùng tập fragment và flag cùng loại vấn đề với cùng lý do giải thích.
+
+## Duy trì knowledge base
+
+### Khi nào nên thêm fragment mới
+
+**Nên thêm khi:**
+
+- Pattern được dùng ở nhiều workflow
+- Chuẩn đó không hiển nhiên
+- Team liên tục hỏi "nên làm X thế nào?"
+- Tích hợp công cụ mới
+
+**Không nên thêm khi:**
+
+- Chỉ là one-off pattern
+- Kiến thức quá hiển nhiên
+- Pattern còn thử nghiệm
+
+### Tiêu chuẩn một fragment tốt
+
+- Nguyên lý gói trong một câu
+- Phần rationale giải thích rõ vì sao
+- Có ít nhất vài ví dụ code
+- Có anti-pattern rõ ràng
+- Có thể đọc độc lập, ít phụ thuộc
+
+**Kích thước tham khảo:** khoảng 10-30 KB là hợp lý.
+
+### Khi nào cần cập nhật fragment hiện có
+
+- Pattern tiến hóa
+- Tool cập nhật API mới
+- Team phản hồi chưa rõ
+- Ví dụ code có lỗi
+
+**Quy trình cập nhật:**
+
+1. Sửa file markdown của fragment
+2. Cập nhật ví dụ
+3. Test lại với các workflow liên quan
+4. Đảm bảo không tạo breaking change ngoài ý muốn
+
+Không cần sửa `tea-index.csv` trừ khi description hoặc tags đổi.
+
+## Lợi ích của knowledge base system
+
+### 1. Tính nhất quán
+
+Trước đây chất lượng test phụ thuộc người viết. Sau đó, test do TEA sinh ra hoặc review đều dựa trên cùng một bộ chuẩn.
+
+### 2. Onboarding
+
+Người mới không cần đọc hàng chục tài liệu trước khi bắt đầu. Họ có thể chạy workflow như `atdd`, xem code được sinh ra và học trực tiếp từ pattern chuẩn.
+
+### 3. Quality gates khách quan
+
+Thay vì tranh luận "test này có tốt không", `test-review` có thể chấm theo cùng tiêu chuẩn từ knowledge base.
+
+### 4. Tiến hóa pattern tập trung
+
+Chỉ cần cập nhật fragment một lần, các test mới về sau sẽ đi theo pattern mới.
+
+### 5. Tái sử dụng giữa nhiều dự án
+
+Không phải phát minh lại pattern cho từng repo. Cùng một hệ chuẩn có thể dùng lại trên nhiều dự án BMad.
+
+## So sánh có và không có knowledge base
+
+### Tình huống: kiểm thử background job bất đồng bộ
+
+**Không có knowledge base:**
+
+Developer 1:
+
+```typescript
+await page.click('button');
+await page.waitForTimeout(10000);
+```
+
+Developer 2:
+
+```typescript
+await page.click('button');
+for (let i = 0; i < 10; i++) {
+ const status = await page.locator('.status').textContent();
+ if (status === 'complete') break;
+ await page.waitForTimeout(1000);
+}
+```
+
+Developer 3:
+
+```typescript
+await page.click('button');
+await page.waitForSelector('.success', { timeout: 30000 });
+```
+
+**Có knowledge base:**
+
+Tất cả sẽ nghiêng về cùng một pattern, ví dụ network-first hoặc theo standard polling đã được tài liệu hóa, thay vì mỗi người làm một kiểu.
+
+## Điều này quan trọng thế nào với QC
+
+Với QC, knowledge base giúp:
+
+- giảm phụ thuộc vào prompt wording
+- giảm độ lệch giữa người này và người khác
+- dễ review vì có chuẩn viện dẫn
+- nâng chất lượng đầu ra AI từ "có lúc hay" thành "ổn định và tái lặp"
+
+## Tài liệu liên quan
+
+- [Knowledge base index](/docs/vi-vn/reference/knowledge-base.md)
+- [Test quality standards](/docs/vi-vn/explanation/test-quality-standards.md)
+- [Fixture architecture](/docs/vi-vn/explanation/fixture-architecture.md)
+- [Network-first patterns](/docs/vi-vn/explanation/network-first-patterns.md)
+- [TEA overview](/docs/vi-vn/explanation/tea-overview.md)
+
+## Kết luận
+
+Knowledge base là phần biến TEA từ một bộ prompt thông minh thành một hệ thống context engineering có chuẩn, có tính lặp lại và có khả năng mở rộng.
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/explanation/network-first-patterns.md b/docs/vi-vn/explanation/network-first-patterns.md
new file mode 100644
index 0000000..7663022
--- /dev/null
+++ b/docs/vi-vn/explanation/network-first-patterns.md
@@ -0,0 +1,657 @@
+---
+title: 'Giải thích network-first patterns'
+description: Hiểu cách TEA loại bỏ flaky test bằng cách chờ đúng phản hồi network thực sự
+---
+
+# Giải thích network-first patterns
+
+Network-first patterns là lời giải của TEA cho flaky test. Thay vì đoán cần đợi bao lâu bằng timeout cố định, hãy đợi đúng sự kiện network dẫn tới thay đổi trên UI.
+
+## Tổng quan
+
+**Nguyên lý cốt lõi:**
+UI thay đổi vì API trả về dữ liệu. Hãy chờ phản hồi API, không phải một timeout tùy ý.
+
+**Cách truyền thống:**
+
+```typescript
+await page.click('button');
+await page.waitForTimeout(3000); // Hy vọng 3 giây là đủ
+await expect(page.locator('.success')).toBeVisible();
+```
+
+**Cách network-first:**
+
+```typescript
+const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/submit') && resp.ok());
+await page.click('button');
+await responsePromise; // Chờ phản hồi thực sự
+await expect(page.locator('.success')).toBeVisible();
+```
+
+**Kết quả:** test có tính xác định, chỉ chờ đúng lượng thời gian cần thiết.
+
+## Vấn đề cần giải quyết
+
+### Hard wait tạo ra flakiness
+
+```typescript
+test('should submit form', async ({ page }) => {
+ await page.fill('#name', 'Test User');
+ await page.click('button[type=\"submit\"]');
+
+ await page.waitForTimeout(2000);
+
+ await expect(page.locator('.success')).toBeVisible();
+});
+```
+
+**Vì sao pattern này dễ fail:**
+
+- **Mạng nhanh:** lãng phí thời gian chờ
+- **Mạng chậm:** chờ chưa đủ, test fail
+- **Môi trường CI:** thường chậm hơn local, fail ngẫu nhiên
+- **Khi hệ thống chịu tải:** API mất 3 giây thay vì 2 giây
+
+**Kết quả:** hội chứng "máy em chạy được", CI thì flaky.
+
+### Bẫy tăng timeout liên tục
+
+```typescript
+await page.waitForTimeout(2000); // Fail trong CI
+await page.waitForTimeout(5000); // Vẫn thỉnh thoảng fail
+await page.waitForTimeout(10000); // Pass, nhưng rất chậm
+```
+
+Vấn đề là từ thời điểm đó **mọi test đều phải chờ 10 giây**, dù API chỉ mất vài trăm mili giây.
+
+### Race condition
+
+```typescript
+test('should load dashboard data', async ({ page }) => {
+ await page.goto('/dashboard');
+
+ await expect(page.locator('.data-table')).toBeVisible();
+});
+```
+
+Điều có thể xảy ra:
+
+1. `goto()` bắt đầu điều hướng
+2. Trang tải HTML
+3. JavaScript gọi `/api/dashboard`
+4. Test kiểm tra `.data-table` trước khi API trả về
+5. Test fail ngắt quãng
+
+## Giải pháp: intercept-before-navigate
+
+### Chờ response trước khi assert
+
+```typescript
+test('should load dashboard data', async ({ page }) => {
+ const dashboardPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+ await page.goto('/dashboard');
+
+ const response = await dashboardPromise;
+ const data = await response.json();
+
+ await expect(page.locator('.data-table')).toBeVisible();
+ await expect(page.locator('.data-table tr')).toHaveCount(data.items.length);
+});
+```
+
+**Vì sao cách này hiệu quả:**
+
+- Thiết lập wait **trước** khi điều hướng, nên không bỏ lỡ response
+- Chờ đúng API thật sự
+- Không cần timeout cố định
+- Có thể validate luôn phản hồi backend
+
+**Với Playwright Utils, code gọn hơn:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+import { expect } from '@playwright/test';
+
+test('should load dashboard data', async ({ page, interceptNetworkCall }) => {
+ const dashboardCall = interceptNetworkCall({
+ method: 'GET',
+ url: '**/api/dashboard',
+ });
+
+ await page.goto('/dashboard');
+
+ const { status, responseJson: data } = await dashboardCall;
+
+ expect(status).toBe(200);
+ expect(data.items).toBeDefined();
+
+ await expect(page.locator('.data-table')).toBeVisible();
+ await expect(page.locator('.data-table tr')).toHaveCount(data.items.length);
+});
+```
+
+**Điểm mạnh của Playwright Utils:**
+
+- Parse JSON tự động
+- Trả về `{ status, responseJson, requestJson }`
+- API ngắn gọn hơn
+- Vẫn giữ đúng pattern intercept-before-navigate
+
+### Pattern chuẩn: Intercept → Action → Await
+
+```typescript
+const promise = page.waitForResponse(matcher);
+await page.click('button');
+await promise;
+```
+
+**Vì sao thứ tự này quan trọng:**
+
+- `waitForResponse()` bắt đầu lắng nghe ngay lập tức
+- Sau đó mới kích hoạt action tạo request
+- Cuối cùng mới `await` promise
+- Gần như loại bỏ race condition do lỡ mất response
+
+#### Luồng intercept-before-navigate
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'14px'}}}%%
+sequenceDiagram
+ participant Test
+ participant Playwright
+ participant Browser
+ participant API
+
+ rect rgb(200, 230, 201)
+ Note over Test,Playwright: ✅ ĐÚNG: Intercept trước
+ Test->>Playwright: 1. waitForResponse(matcher)
+ Note over Playwright: Bắt đầu lắng nghe response
+ Test->>Browser: 2. click('button')
+ Browser->>API: 3. POST /api/submit
+ API-->>Browser: 4. 200 OK {success: true}
+ Browser-->>Playwright: 5. Response được bắt
+ Test->>Playwright: 6. await promise
+ Playwright-->>Test: 7. Trả về response
+ Note over Test: Không có race condition
+ end
+
+ rect rgb(255, 205, 210)
+ Note over Test,API: ❌ SAI: Action trước
+ Test->>Browser: 1. click('button')
+ Browser->>API: 2. POST /api/submit
+ API-->>Browser: 3. 200 OK (đã xảy ra xong)
+ Test->>Playwright: 4. waitForResponse(matcher)
+ Note over Test,Playwright: Quá muộn, response đã qua
+ Note over Test: Race condition, test treo hoặc fail
+ end
+```
+
+## TEA áp dụng network-first như thế nào
+
+### TEA sinh test theo network-first
+
+**Vanilla Playwright:**
+
+```typescript
+test('should create user', async ({ page }) => {
+ const createUserPromise = page.waitForResponse(
+ (resp) => resp.url().includes('/api/users') && resp.request().method() === 'POST' && resp.ok(),
+ );
+
+ await page.fill('#name', 'Test User');
+ await page.click('button[type=\"submit\"]');
+
+ const response = await createUserPromise;
+ const user = await response.json();
+
+ expect(user.id).toBeDefined();
+ await expect(page.locator('.success')).toContainText(user.name);
+});
+```
+
+**Với Playwright Utils nếu `tea_use_playwright_utils: true`:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+import { expect } from '@playwright/test';
+
+test('should create user', async ({ page, interceptNetworkCall }) => {
+ const createUserCall = interceptNetworkCall({
+ method: 'POST',
+ url: '**/api/users',
+ });
+
+ await page.getByLabel('Name').fill('Test User');
+ await page.getByRole('button', { name: 'Submit' }).click();
+
+ const { status, responseJson: user } = await createUserCall;
+
+ expect(status).toBe(201);
+ expect(user.id).toBeDefined();
+ await expect(page.locator('.success')).toContainText(user.name);
+});
+```
+
+### TEA review hard wait
+
+Khi chạy `test-review`, TEA sẽ đánh dấu hard wait như một lỗi nghiêm trọng:
+
+````markdown
+## Critical Issue: Hard Wait Detected
+
+**File:** tests/e2e/submit.spec.ts:45
+**Issue:** Using `page.waitForTimeout(3000)`
+**Severity:** Critical (causes flakiness)
+
+**Current Code:**
+
+```typescript
+await page.click('button');
+await page.waitForTimeout(3000); // ❌
+```
+````
+
+**Fix:**
+
+```typescript
+const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/submit') && resp.ok());
+await page.click('button');
+await responsePromise; // ✅
+```
+
+**Vì sao:** hard wait là không xác định. Hãy dùng network-first patterns.
+
+````
+
+## Các biến thể phổ biến
+
+### Basic response wait
+
+**Vanilla Playwright:**
+
+```typescript
+const promise = page.waitForResponse((resp) => resp.ok());
+await page.click('button');
+await promise;
+```
+
+**Với Playwright Utils:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('basic wait', async ({ page, interceptNetworkCall }) => {
+ const responseCall = interceptNetworkCall({ url: '**' });
+ await page.click('button');
+ const { status } = await responseCall;
+ expect(status).toBe(200);
+});
+```
+
+### Match URL cụ thể
+
+```typescript
+const promise = page.waitForResponse((resp) => resp.url().includes('/api/users/123'));
+await page.goto('/user/123');
+await promise;
+```
+
+```typescript
+test('specific URL', async ({ page, interceptNetworkCall }) => {
+ const userCall = interceptNetworkCall({ url: '**/api/users/123' });
+ await page.goto('/user/123');
+ const { status, responseJson } = await userCall;
+ expect(status).toBe(200);
+});
+```
+
+### Match method và status
+
+```typescript
+const promise = page.waitForResponse(
+ (resp) => resp.url().includes('/api/users') && resp.request().method() === 'POST' && resp.status() === 201,
+);
+await page.click('button[type=\"submit\"]');
+await promise;
+```
+
+```typescript
+test('method and status', async ({ page, interceptNetworkCall }) => {
+ const createCall = interceptNetworkCall({
+ method: 'POST',
+ url: '**/api/users',
+ });
+ await page.click('button[type=\"submit\"]');
+ const { status, responseJson } = await createCall;
+ expect(status).toBe(201);
+});
+```
+
+### Nhiều response cùng lúc
+
+```typescript
+const [usersResp, postsResp] = await Promise.all([
+ page.waitForResponse((resp) => resp.url().includes('/api/users')),
+ page.waitForResponse((resp) => resp.url().includes('/api/posts')),
+ page.goto('/dashboard'),
+]);
+
+const users = await usersResp.json();
+const posts = await postsResp.json();
+```
+
+```typescript
+test('multiple responses', async ({ page, interceptNetworkCall }) => {
+ const usersCall = interceptNetworkCall({ url: '**/api/users' });
+ const postsCall = interceptNetworkCall({ url: '**/api/posts' });
+
+ await page.goto('/dashboard');
+
+ const [{ responseJson: users }, { responseJson: posts }] = await Promise.all([usersCall, postsCall]);
+
+ expect(users).toBeInstanceOf(Array);
+ expect(posts).toBeInstanceOf(Array);
+});
+```
+
+### Validate dữ liệu response trước khi assert UI
+
+```typescript
+const promise = page.waitForResponse((resp) => resp.url().includes('/api/checkout') && resp.ok());
+
+await page.click('button:has-text(\"Complete Order\")');
+
+const response = await promise;
+const order = await response.json();
+
+expect(order.status).toBe('confirmed');
+expect(order.total).toBeGreaterThan(0);
+
+await expect(page.locator('.order-confirmation')).toContainText(order.id);
+```
+
+```typescript
+test('validate response data', async ({ page, interceptNetworkCall }) => {
+ const checkoutCall = interceptNetworkCall({
+ method: 'POST',
+ url: '**/api/checkout',
+ });
+
+ await page.click('button:has-text(\"Complete Order\")');
+
+ const { status, responseJson: order } = await checkoutCall;
+
+ expect(status).toBe(200);
+ expect(order.status).toBe('confirmed');
+ expect(order.total).toBeGreaterThan(0);
+
+ await expect(page.locator('.order-confirmation')).toContainText(order.id);
+});
+```
+
+## Advanced patterns
+
+### Ghi HAR để test offline
+
+**Vanilla Playwright:**
+
+```typescript
+test('offline testing - RECORD', async ({ page, context }) => {
+ await context.routeFromHAR('./hars/dashboard.har', {
+ url: '**/api/**',
+ update: true,
+ });
+
+ await page.goto('/dashboard');
+});
+
+test('offline testing - PLAYBACK', async ({ page, context }) => {
+ await context.routeFromHAR('./hars/dashboard.har', {
+ url: '**/api/**',
+ update: false,
+ });
+
+ await page.goto('/dashboard');
+});
+```
+
+**Với Playwright Utils:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+process.env.PW_NET_MODE = 'record';
+
+test('should work offline', async ({ page, context, networkRecorder }) => {
+ await networkRecorder.setup(context);
+
+ await page.goto('/dashboard');
+ await page.click('#add-item');
+});
+```
+
+Chuyển sang playback:
+
+```bash
+PW_NET_MODE=playback npx playwright test
+```
+
+### Intercept request để giả lập lỗi API
+
+**Vanilla Playwright:**
+
+```typescript
+test('should handle API error', async ({ page }) => {
+ await page.route('**/api/users', (route) => {
+ route.fulfill({
+ status: 500,
+ body: JSON.stringify({ error: 'Internal server error' }),
+ });
+ });
+
+ await page.goto('/users');
+
+ const response = await page.waitForResponse('**/api/users');
+ const error = await response.json();
+
+ expect(error.error).toContain('Internal server');
+ await expect(page.locator('.error-message')).toContainText('Server error');
+});
+```
+
+**Với Playwright Utils:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should handle API error', async ({ page, interceptNetworkCall }) => {
+ const usersCall = interceptNetworkCall({
+ method: 'GET',
+ url: '**/api/users',
+ fulfillResponse: {
+ status: 500,
+ body: { error: 'Internal server error' },
+ },
+ });
+
+ await page.goto('/users');
+
+ const { status, responseJson } = await usersCall;
+
+ expect(status).toBe(500);
+ expect(responseJson.error).toContain('Internal server');
+ await expect(page.locator('.error-message')).toContainText('Server error');
+});
+```
+
+## So sánh: truyền thống và network-first
+
+### Tải dữ liệu dashboard
+
+**Truyền thống, dễ flaky:**
+
+```typescript
+test('dashboard loads data', async ({ page }) => {
+ await page.goto('/dashboard');
+ await page.waitForTimeout(2000);
+ await expect(page.locator('table tr')).toHaveCount(5);
+});
+```
+
+**Network-first, có tính xác định:**
+
+```typescript
+test('dashboard loads data', async ({ page }) => {
+ const apiPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+ await page.goto('/dashboard');
+
+ const response = await apiPromise;
+ const { items } = await response.json();
+
+ expect(items).toHaveLength(5);
+ await expect(page.locator('table tr')).toHaveCount(items.length);
+});
+```
+
+**Với Playwright Utils:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('dashboard loads data', async ({ page, interceptNetworkCall }) => {
+ const dashboardCall = interceptNetworkCall({
+ method: 'GET',
+ url: '**/api/dashboard',
+ });
+
+ await page.goto('/dashboard');
+
+ const {
+ status,
+ responseJson: { items },
+ } = await dashboardCall;
+
+ expect(status).toBe(200);
+ expect(items).toHaveLength(5);
+ await expect(page.locator('table tr')).toHaveCount(items.length);
+});
+```
+
+### Submit form
+
+```typescript
+test('form submission', async ({ page }) => {
+ await page.fill('#email', 'test@example.com');
+ await page.click('button[type=\"submit\"]');
+ await page.waitForTimeout(3000);
+ await expect(page.locator('.success')).toBeVisible();
+});
+```
+
+```typescript
+test('form submission', async ({ page }) => {
+ const submitPromise = page.waitForResponse(
+ (resp) => resp.url().includes('/api/submit') && resp.request().method() === 'POST' && resp.ok(),
+ );
+
+ await page.fill('#email', 'test@example.com');
+ await page.click('button[type=\"submit\"]');
+
+ const response = await submitPromise;
+ const result = await response.json();
+
+ expect(result.success).toBe(true);
+ await expect(page.locator('.success')).toBeVisible();
+});
+```
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('form submission', async ({ page, interceptNetworkCall }) => {
+ const submitCall = interceptNetworkCall({
+ method: 'POST',
+ url: '**/api/submit',
+ });
+
+ await page.getByLabel('Email').fill('test@example.com');
+ await page.getByRole('button', { name: 'Submit' }).click();
+
+ const { status, responseJson: result } = await submitCall;
+
+ expect(status).toBe(200);
+ expect(result.success).toBe(true);
+ await expect(page.locator('.success')).toBeVisible();
+});
+```
+
+## Các hiểu lầm thường gặp
+
+### "Tôi đã dùng waitForSelector rồi"
+
+```typescript
+await page.click('button');
+await page.waitForSelector('.success', { timeout: 5000 });
+```
+
+Vấn đề là bạn đang đợi DOM, chưa đợi nguyên nhân gốc là API.
+
+**Tốt hơn:**
+
+```typescript
+await page.waitForResponse(matcher);
+await page.waitForSelector('.success');
+```
+
+### "Test của tôi nhanh, sao phải thêm phức tạp"
+
+Ngắn hạn có thể vẫn ổn trên máy local. Nhưng về dài hạn:
+
+- CI chậm hơn local
+- Hệ thống khi tải cao sẽ chậm hơn
+- Mạng biến động
+- Suite mở rộng từ 100 lên 1000 test
+
+Network-first ngăn các vấn đề đó trước khi chúng bùng lên.
+
+### "Quá nhiều boilerplate"
+
+Nếu thấy `waitForResponse` lặp lại quá nhiều, dùng `interceptNetworkCall` của Playwright Utils để gom phần boilerplate đó vào fixture.
+
+## Triển khai kỹ thuật
+
+Xem thêm trong knowledge base:
+
+- [Knowledge Base Index - Network & Reliability](/docs/vi-vn/reference/knowledge-base.md)
+- [Complete Knowledge Base Index](/docs/vi-vn/reference/knowledge-base.md)
+
+## Khái niệm liên quan
+
+- [Tiêu chuẩn chất lượng test](/docs/vi-vn/explanation/test-quality-standards.md) - determinism đòi hỏi network-first
+- [Risk-based testing](/docs/vi-vn/explanation/risk-based-testing.md) - tính ổn định càng quan trọng ở vùng rủi ro cao
+- [Fixture architecture](/docs/vi-vn/explanation/fixture-architecture.md) - network utilities có thể được đóng gói thành fixture
+- [Knowledge base system](/docs/vi-vn/explanation/knowledge-base-system.md) - nơi các pattern network-first được lưu lại
+- [TEA overview](/docs/vi-vn/explanation/tea-overview.md) - network-first xuất hiện trong các workflow của TEA
+- [Testing as engineering](/docs/vi-vn/explanation/testing-as-engineering.md) - vì sao flakiness là vấn đề vận hành thực sự
+
+## Hướng dẫn thực hành
+
+- [Cách chạy test-review](/docs/vi-vn/how-to/workflows/run-test-review.md) - tìm và sửa hard wait
+- [Cách chạy ATDD](/docs/vi-vn/how-to/workflows/run-atdd.md) - sinh test theo network-first
+- [Cách chạy automate](/docs/vi-vn/how-to/workflows/run-automate.md) - mở rộng test với network patterns
+- [Dùng TEA với test hiện có](/docs/vi-vn/how-to/brownfield/use-tea-with-existing-tests.md) - làm sạch legacy flaky tests
+- [Tích hợp Playwright Utils](/docs/vi-vn/how-to/customization/integrate-playwright-utils.md) - các utility về network recorder, interceptor và error monitor
+
+## Tham chiếu
+
+- [TEA command reference](/docs/vi-vn/reference/commands.md)
+- [Knowledge base index](/docs/vi-vn/reference/knowledge-base.md)
+- [Glossary](/docs/vi-vn/glossary/index.md#test-architect-tea-concepts)
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
+````
diff --git a/docs/vi-vn/explanation/risk-based-testing.md b/docs/vi-vn/explanation/risk-based-testing.md
new file mode 100644
index 0000000..11460e7
--- /dev/null
+++ b/docs/vi-vn/explanation/risk-based-testing.md
@@ -0,0 +1,281 @@
+---
+title: 'Giải thích risk-based testing'
+description: Hiểu cách TEA dùng điểm probability × impact để ưu tiên nỗ lực kiểm thử
+---
+
+# Giải thích risk-based testing
+
+Risk-based testing là nguyên lý cốt lõi của TEA: độ sâu kiểm thử phải tăng theo tác động kinh doanh. Thay vì kiểm mọi thứ như nhau, hãy dồn công sức vào nơi mà failure gây đau nhất.
+
+## Tổng quan
+
+Cách tiếp cận truyền thống thường đối xử các feature ngang nhau:
+
+- Feature nào cũng được số lượng test tương tự
+- Mức review như nhau bất kể tác động
+- Không có ưu tiên có hệ thống
+- Kiểm thử dễ biến thành checklist hình thức
+
+Risk-based testing đặt ba câu hỏi:
+
+- Khả năng feature này hỏng là bao nhiêu?
+- Nếu hỏng thì tác động nghiêm trọng cỡ nào?
+- Với mức rủi ro đó, nên đầu tư kiểm thử đến đâu?
+
+## Vấn đề
+
+### Kiểm thử ngang nhau cho các rủi ro không ngang nhau
+
+```markdown
+Feature A: đăng nhập người dùng, critical path, hàng triệu user
+Feature B: xuất PDF, tính năng nice-to-have, rất ít dùng
+
+Nếu cả hai đều được 10 test và mức scrutiny giống nhau,
+ta đang lãng phí effort ở chỗ ít quan trọng và under-test chỗ sống còn.
+```
+
+### Không có cách ưu tiên khách quan
+
+```markdown
+PM: "Cần test checkout kỹ hơn"
+QA: "Kỹ đến mức nào?"
+PM: "Không rõ, nhưng nhiều hơn"
+```
+
+Không có score thì mọi quyết định dễ thành tranh luận chủ quan.
+
+## Lời giải: chấm điểm Probability × Impact
+
+### Điểm rủi ro = Probability × Impact
+
+**Probability** - khả năng xảy ra lỗi:
+
+- **1 thấp**: logic đơn giản, đã ổn định
+- **2 trung bình**: có độ phức tạp vừa phải, còn ẩn số
+- **3 cao**: phức tạp, mới, nhiều edge case
+
+**Impact** - mức độ thiệt hại nếu lỗi xảy ra:
+
+- **1 thấp**: chỉ là bất tiện nhỏ
+- **2 trung bình**: trải nghiệm suy giảm nhưng có workaround
+- **3 cao**: vỡ critical path hoặc ảnh hưởng kinh doanh rõ
+
+**Thang điểm:** từ 1 đến 9
+
+### Ma trận rủi ro
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'fontSize':'14px'}}}%%
+graph TD
+ subgraph Matrix[" "]
+ direction TB
+ subgraph Impact3["Impact: HIGH (3)"]
+ P1I3["Score: 3
Low Risk"]
+ P2I3["Score: 6
HIGH RISK
Mitigation Required"]
+ P3I3["Score: 9
CRITICAL
Blocks Release"]
+ end
+ subgraph Impact2["Impact: MEDIUM (2)"]
+ P1I2["Score: 2
Low Risk"]
+ P2I2["Score: 4
Medium Risk"]
+ P3I2["Score: 6
HIGH RISK
Mitigation Required"]
+ end
+ subgraph Impact1["Impact: LOW (1)"]
+ P1I1["Score: 1
Low Risk"]
+ P2I1["Score: 2
Low Risk"]
+ P3I1["Score: 3
Low Risk"]
+ end
+ end
+```
+
+**Cách đọc nhanh:**
+
+- **9**: critical, có thể chặn release
+- **6-8**: high risk, cần mitigation rõ
+- **4-5**: medium, nên có mitigation
+- **1-3**: low, có thể kiểm tối thiểu
+
+### Ví dụ chấm điểm
+
+**Score 9 - cực kỳ quan trọng**
+
+```text
+Feature: xử lý thanh toán
+Probability: 3, vì tích hợp bên thứ ba phức tạp
+Impact: 3, vì hỏng thanh toán là mất doanh thu
+Score: 9
+```
+
+**Hành động gợi ý:**
+
+- E2E cho tất cả payment flow chính
+- API test cho các scenario thanh toán
+- Error handling cho failure mode
+- Security test
+- Load test khi lưu lượng cao
+- Monitoring và alert
+
+**Score 1 - rủi ro thấp**
+
+```text
+Feature: đổi màu theme profile
+Probability: 1
+Impact: 1
+Score: 1
+```
+
+**Hành động gợi ý:**
+
+- Một smoke test là đủ
+- Bỏ qua edge case ít giá trị
+- Không nhất thiết cần API test
+
+**Score 6 - trung bình cao**
+
+```text
+Feature: chỉnh sửa thông tin hồ sơ
+Probability: 2
+Impact: 3
+Score: 6
+```
+
+**Hành động gợi ý:**
+
+- E2E cho happy path
+- API test cho CRUD
+- Validation test
+- Không cần ôm mọi edge case nhỏ
+
+## TEA áp dụng risk-based testing thế nào
+
+### 1. Sáu nhóm rủi ro
+
+TEA thường đánh giá theo 6 nhóm:
+
+**TECH** - technical debt, fragility, thay đổi kiến trúc
+**SEC** - bảo mật, xác thực, phân quyền
+**PERF** - suy giảm hiệu năng, load, độ trễ
+**DATA** - toàn vẹn dữ liệu, migration, corruption
+**BUS** - lỗi business logic ảnh hưởng nghiệp vụ
+**OPS** - rủi ro vận hành, logging, monitoring, deployability
+
+Ví dụ:
+
+- **TECH**: chuyển từ REST sang GraphQL, score có thể rất cao
+- **SEC**: thêm OAuth, cần security testing bắt buộc
+- **PERF**: thêm realtime notification, cần load test nếu score tăng
+- **DATA**: migration schema, cần data validation test
+- **BUS**: tính khuyến mãi sai, cần business-rule tests
+- **OPS**: sửa hệ thống log, có thể chỉ cần smoke test nếu impact thấp
+
+### 2. Độ ưu tiên test P0-P3
+
+Điểm rủi ro ảnh hưởng trực tiếp tới mức ưu tiên:
+
+**P0 - Critical path**
+
+- Thường score 6-9
+- Có thể cộng thêm yếu tố doanh thu, bảo mật, tuân thủ, usage frequency
+- Mục tiêu coverage rất cao
+- Thường cần cả E2E và API
+
+**P1 - High value**
+
+- Thường score 4-6
+- Là core journey hoặc logic phức tạp
+- Chủ yếu API + selective E2E
+
+**P2 - Medium value**
+
+- Thường score 2-4
+- Feature phụ trợ, admin, reporting
+- Coverage vừa phải
+
+**P3 - Low value**
+
+- Điểm thấp, ít tác động
+- Chỉ cần smoke hoặc kiểm tra tối thiểu
+
+## Risk-based testing thay đổi chiến lược test ra sao
+
+### Với feature rủi ro cao
+
+- test nhiều tầng hơn
+- đòi hỏi evidence rõ hơn
+- review khắt khe hơn
+- có thể cần traceability và gate decision riêng
+
+### Với feature rủi ro thấp
+
+- tránh over-testing
+- ưu tiên smoke hoặc test đại diện
+- không tiêu tốn thời gian vào edge case hiếm
+
+## Tác động đến workflow của TEA
+
+### `test-design`
+
+Đây là nơi risk-based testing phát huy mạnh nhất. `test-design` dùng score để:
+
+- xác định vùng cần test sâu
+- gán priority P0-P3
+- quyết định nên tập trung vào E2E, API hay integration
+- viết mitigation plan theo mức rủi ro
+
+### `atdd` và `automate`
+
+Khi sinh test, độ sâu và phạm vi có thể thay đổi theo risk score:
+
+- high-risk feature sẽ có nhiều scenario hơn
+- low-risk feature sẽ gọn hơn
+- selector, fixture và validation cũng được ưu tiên theo giá trị
+
+### `trace`
+
+Không phải mọi khoảng trống coverage đều nghiêm trọng như nhau. Với `trace`, vùng coverage thiếu ở P0/P1 sẽ đáng lo hơn nhiều so với vùng thấp rủi ro.
+
+### `nfr-assess`
+
+Một feature có risk score cao ở PERF, SEC hoặc DATA thường kéo theo nhu cầu đánh giá NFR sâu hơn, thay vì chỉ nhìn functional pass/fail.
+
+## Lợi ích thực tế
+
+### 1. Dùng effort đúng chỗ
+
+Team không còn đổ cùng một lượng công sức vào feature ít quan trọng và feature critical.
+
+### 2. Quyết định bớt cảm tính
+
+Có điểm số giúp đối thoại giữa PM, QC, DEV và architect bớt tranh luận chung chung.
+
+### 3. Dễ bảo vệ quality gate
+
+Khi release bị chặn vì score cao mà mitigation chưa đủ, quyết định đó có nền tảng rõ hơn.
+
+### 4. Phù hợp với enterprise
+
+Trong môi trường compliance hoặc hệ thống lớn, risk-based testing giúp justify vì sao có nơi cần audit kỹ hơn nơi khác.
+
+## Điều này quan trọng thế nào với QC
+
+Với QC, risk-based testing là công cụ để:
+
+- ưu tiên effort trong backlog test
+- nói chuyện với PM và DEV bằng tiêu chí rõ
+- tránh test quá nông ở vùng critical
+- đồng thời tránh lãng phí ở feature rủi ro thấp
+
+## Tài liệu liên quan
+
+- [Test quality standards](/docs/vi-vn/explanation/test-quality-standards.md)
+- [TEA overview](/docs/vi-vn/explanation/tea-overview.md)
+- [Cách chạy test-design](/docs/vi-vn/how-to/workflows/run-test-design.md)
+- [Cách chạy trace](/docs/vi-vn/how-to/workflows/run-trace.md)
+- [Cách chạy nfr-assess](/docs/vi-vn/how-to/workflows/run-nfr-assess.md)
+
+## Kết luận
+
+Risk-based testing không có nghĩa là test ít đi. Nó có nghĩa là **test đúng chỗ, đúng độ sâu và đúng mức bằng chứng** so với rủi ro thật của hệ thống.
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/explanation/step-file-architecture.md b/docs/vi-vn/explanation/step-file-architecture.md
new file mode 100644
index 0000000..c85e83d
--- /dev/null
+++ b/docs/vi-vn/explanation/step-file-architecture.md
@@ -0,0 +1,481 @@
+---
+title: Kiến trúc step-file của TEA
+description: Giải thích kiến trúc step-file để đạt mức tuân thủ LLM gần như tuyệt đối
+---
+
+# Kiến trúc step-file của TEA
+
+**Phiên bản**: 1.0
+**Ngày**: 2026-01-27
+**Mục đích**: giải thích kiến trúc step-file nhằm đạt mức tuân thủ LLM gần như 100%
+
+---
+
+## Vì sao cần step file
+
+### Bài toán
+
+Các file hướng dẫn workflow kiểu truyền thống thường gặp hội chứng "quá nhiều context":
+
+- **LLM dễ ứng biến sai**: khi nhận file chỉ dẫn quá lớn, mô hình dễ bỏ sót bước hoặc tự thêm hành vi
+- **Không tuân thủ chặt**: chỉ dẫn kiểu "phân tích codebase rồi sinh test" quá mơ hồ
+- **Quá tải context**: file 5000 từ làm cửa sổ ngữ cảnh bị lãng phí
+- **Đầu ra khó đoán**: cùng một workflow có thể cho kết quả khác nhau ở mỗi lần chạy
+
+### Lời giải: step files
+
+**Step files** chia workflow thành những đơn vị chỉ dẫn nhỏ, tự đầy đủ:
+
+- **Một step = một hành động rõ ràng**
+- **Điều kiện thoát tường minh**
+- **Inject context vào từng bước**
+- **Ngăn mô hình ứng biến ngoài phạm vi**
+
+**Kết quả**: workflow ổn định hơn, dự đoán được hơn và nhất quán hơn.
+
+---
+
+## Tổng quan kiến trúc
+
+### Trước khi có step files
+
+```text
+workflow/
+├── workflow.yaml
+├── instructions.md
+├── checklist.md
+└── templates/
+```
+
+**Vấn đề:**
+
+- Chỉ dẫn quá dài nên dễ bị lướt qua
+- Không có điểm dừng rõ
+- Hướng dẫn mơ hồ nên mỗi lần hiểu một kiểu
+
+### Sau khi có step files
+
+```text
+workflow/
+├── workflow.yaml
+├── checklist.md
+├── templates/
+└── steps/
+ ├── step-1-setup.md
+ ├── step-2-analyze.md
+ ├── step-3-generate.md
+ └── step-4-validate.md
+```
+
+**Lợi ích:**
+
+- Chỉ dẫn hạt mịn, tập trung từng việc
+- Có điều kiện kết thúc rõ ràng
+- Lặp lại context cần thiết
+- Hỗ trợ subagent và chạy song song
+
+---
+
+## Các nguyên tắc của step file
+
+### 1. Nạp đúng lúc, just-in-time loading
+
+**Chỉ nạp step hiện tại**, không nạp toàn bộ các step cùng lúc.
+
+```yaml
+steps:
+ - file: steps/step-1-setup.md
+ next: steps/step-2-analyze.md
+ - file: steps/step-2-analyze.md
+ next: steps/step-3-generate.md
+```
+
+Agent đọc **một file step**, thực thi xong rồi mới nạp step tiếp theo.
+
+### 2. Context injection
+
+Mỗi step **lặp lại phần context bắt buộc**, không giả định LLM nhớ chính xác mọi thứ từ bước trước.
+
+```markdown
+## Context (from previous steps)
+
+You have:
+
+- Analyzed codebase and identified 3 features: Auth, Checkout, Profile
+- Loaded knowledge fragments: fixture-architecture, api-request, network-first
+- Determined test framework: Playwright with TypeScript
+
+## Your Task (Step 3 Only)
+
+Generate API tests for the 3 features identified above...
+```
+
+### 3. Điều kiện thoát tường minh
+
+Mỗi step phải nói rõ khi nào được chuyển bước.
+
+```markdown
+## Exit Condition
+
+You may proceed to Step 4 when:
+
+- ✅ All API tests generated and saved to files
+- ✅ Test files use knowledge fragment patterns
+- ✅ All tests have .spec.ts extension
+- ✅ Tests are syntactically valid TypeScript
+```
+
+### 4. Ranh giới hành động nghiêm ngặt
+
+Mỗi step phải chỉ ra rõ việc **phải làm** và **không được làm**.
+
+```markdown
+## What You MUST Do
+
+- Generate API tests only
+- Use patterns from loaded knowledge fragments
+- Save to tests/api/ directory
+
+## What You MUST NOT Do
+
+- ❌ Do NOT generate E2E tests
+- ❌ Do NOT run tests yet
+- ❌ Do NOT refactor existing code
+```
+
+### 5. Hỗ trợ subagent
+
+Các step độc lập có thể được tách sang subagent để chạy song song.
+
+Ví dụ ở workflow `automate`:
+
+```text
+Step 1-2: Sequential
+Step 3: Subagent A (API tests) + Subagent B (E2E tests)
+Step 4: Aggregate + validate
+```
+
+Xem thêm [subagent-architecture.md](./subagent-architecture.md).
+
+---
+
+## Các pattern step-file trong workflow TEA
+
+### Pattern 1: Sequential steps
+
+**Dùng cho**: `framework`, `ci`
+
+```text
+Step 1: Setup → Step 2: Configure → Step 3: Generate → Step 4: Validate
+```
+
+Đặc điểm:
+
+- Mỗi bước phụ thuộc đầu ra của bước trước
+- Không song song hóa được
+- Phù hợp cho workflow ngắn và chạy một lần
+
+### Pattern 2: Parallel generation
+
+**Dùng cho**: `automate`, `atdd`
+
+```text
+Step 1: Setup
+Step 2: Load knowledge
+Step 3: PARALLEL
+ ├── Subagent A: Generate API tests
+ └── Subagent B: Generate E2E tests
+Step 4: Aggregate + validate
+```
+
+Đặc điểm:
+
+- Các tác vụ sinh test độc lập chạy song song
+- Cải thiện hiệu năng khoảng 40-50%
+- Là nhóm workflow dùng thường xuyên nhất
+
+### Pattern 3: Parallel validation
+
+**Dùng cho**: `test-review`, `nfr-assess`
+
+```text
+Step 1: Load context
+Step 2: PARALLEL
+ ├── Subagent A: Check dimension 1
+ ├── Subagent B: Check dimension 2
+ ├── Subagent C: Check dimension 3
+Step 3: Aggregate scores
+```
+
+### Pattern 4: Two-phase workflow
+
+**Dùng cho**: `trace`
+
+```text
+Phase 1: Generate coverage matrix
+Phase 2: Read matrix → apply decision tree → generate gate
+```
+
+### Pattern 5: Risk-based planning
+
+**Dùng cho**: `test-design`
+
+```text
+Step 1: Load context
+Step 2: Load knowledge fragments
+Step 3: Assess risk
+Step 4: Generate scenarios
+Step 5: Prioritize
+Step 6: Output test design document
+```
+
+---
+
+## Tích hợp knowledge fragments
+
+### Nạp fragment trong step files
+
+Step files có thể yêu cầu nạp fragment một cách tường minh:
+
+```markdown
+## Step 2: Load Knowledge Fragments
+
+Consult `{project-root}/_bmad/tea/agents/bmad-tea/resources/tea-index.csv` and load:
+
+1. **fixture-architecture**
+2. **api-request**
+3. **network-first**
+```
+
+Các fragment này đóng vai trò như chuẩn chất lượng để áp vào test sinh ra.
+
+### Cưỡng chế việc dùng fragment
+
+```markdown
+## Requirements
+
+Generated tests MUST follow patterns from loaded fragments:
+
+✅ Use fixture composition pattern
+✅ Use await apiRequest() helper
+✅ Intercept before navigate
+
+❌ Do NOT use custom patterns
+❌ Do NOT skip fragment patterns
+```
+
+---
+
+## Mẫu step file chuẩn
+
+### Cấu trúc tiêu chuẩn
+
+```markdown
+# Step N: [Action Name]
+
+## Context (from previous steps)
+
+## Your Task (Step N Only)
+
+## Requirements
+
+## What You MUST Do
+
+## What You MUST NOT Do
+
+## Exit Condition
+
+## Next Step
+```
+
+### Ví dụ step file cho việc sinh API test
+
+```markdown
+# Step 3A: Generate API Tests (Subagent)
+
+## Context (from previous steps)
+
+You have:
+
+- Analyzed codebase and identified 3 features: Auth, Checkout, Profile
+- Loaded knowledge fragments: api-request, data-factories, api-testing-patterns
+- Determined test framework: Playwright with TypeScript
+- Config: use_playwright_utils = true
+
+## Your Task (Step 3A Only)
+
+Generate API tests for the 3 features identified above.
+
+## Requirements
+
+- ✅ Generate tests for all 3 features
+- ✅ Use Playwright Utils `apiRequest()` helper
+- ✅ Use data factories for test data
+- ✅ Save to tests/api/ directory
+
+## What You MUST Do
+
+1. For each feature, create `tests/api/[feature].spec.ts`
+2. Import fixtures và helper cần thiết
+3. Sinh 3-5 test case cho happy path và edge case
+4. Lưu tất cả file xuống đĩa
+
+## What You MUST NOT Do
+
+- ❌ Do NOT generate E2E tests
+- ❌ Do NOT run tests yet
+- ❌ Do NOT hardcode test data
+```
+
+Phần output có thể được ghi ra file JSON tạm để main workflow đọc lại.
+
+---
+
+## Validation và bảo đảm chất lượng
+
+### BMad Builder validation
+
+Tất cả 9 workflow TEA được đánh giá đạt **100%** trên BMad Builder validation. Báo cáo validation nằm trong `src/workflows/testarch/*/validation-report-*.md`.
+
+**Tiêu chí validation:**
+
+- Chỉ dẫn rõ ràng, hạt mịn
+- Có exit condition cụ thể
+- Có context injection
+- Có action boundary chặt chẽ
+- Có hỗ trợ subagent khi cần
+
+### Kiểm thử trên dự án thực
+
+Tất cả 9 workflow đều đã được thử với dự án thật:
+
+- `teach-me-testing`
+- `test-design`
+- `automate`
+- `atdd`
+- `test-review`
+- `nfr-assess`
+- `trace`
+- `framework`
+- `ci`
+
+Mục tiêu là giảm ứng biến ngoài ý muốn và cho đầu ra ổn định hơn.
+
+---
+
+## Duy trì step files
+
+### Khi nào nên cập nhật
+
+Hãy cập nhật step files khi:
+
+1. Knowledge fragments thay đổi
+2. Xuất hiện pattern mới
+3. LLM vẫn còn ứng biến sai
+4. Có vấn đề hiệu năng
+5. Nhận được phản hồi người dùng về điểm chưa rõ
+
+### Best practices
+
+1. Giữ step đủ nhỏ, khoảng 200-500 từ
+2. Lặp lại context cần thiết
+3. Viết thật cụ thể
+4. Ghi rõ điều không được làm
+5. Chạy validation lại sau khi sửa
+
+### Anti-pattern cần tránh
+
+- Step dài quá 1000 từ
+- Chỉ dẫn mơ hồ như "analyze codebase"
+- Không có exit condition
+- Giả định mô hình nhớ chính xác bước trước
+- Nhét nhiều nhiệm vụ vào cùng một step
+
+---
+
+## Lợi ích hiệu năng
+
+### Trước và sau khi có step files
+
+**Trước đây, chạy tuần tự:**
+
+- `automate`: khoảng 10 phút
+- `test-review`: khoảng 5 phút
+- `nfr-assess`: khoảng 12 phút
+
+**Sau khi chia step và dùng subagent:**
+
+- `automate`: khoảng 5 phút, nhanh hơn khoảng 50%
+- `test-review`: khoảng 2 phút, nhanh hơn khoảng 60%
+- `nfr-assess`: khoảng 4 phút, nhanh hơn khoảng 67%
+
+### Người dùng nhìn thấy gì
+
+Người dùng không cần hiểu nội bộ step-file, nhưng sẽ thấy:
+
+1. Đầu ra ổn định hơn
+2. Workflow nhanh hơn
+3. Chất lượng đều tay hơn
+4. Hành vi ít bất ngờ hơn
+
+Ví dụ tiến trình:
+
+```text
+✓ Step 1: Setup complete
+✓ Step 2: Knowledge fragments loaded
+⟳ Step 3: Generating tests (2 subagents running)
+ ├── Subagent A: API tests... ✓
+ └── Subagent B: E2E tests... ✓
+✓ Step 4: Aggregating results
+✓ Step 5: Validation complete
+```
+
+---
+
+## Troubleshooting
+
+### Sự cố thường gặp
+
+**LLM vẫn ứng biến sai dù đã có step files**
+
+- Chẩn đoán: chỉ dẫn vẫn còn mơ hồ
+- Cách sửa: thêm requirements và forbidden actions rõ hơn
+
+**Output từ subagent không được aggregate đúng**
+
+- Chẩn đoán: lệch đường dẫn file tạm hoặc lỗi parse JSON
+- Cách sửa: kiểm tra naming convention và format JSON
+
+**Knowledge fragments không được dùng**
+
+- Chẩn đoán: phần hướng dẫn nạp fragment chưa đủ rõ
+- Cách sửa: viết requirement rõ và ràng buộc hơn
+
+**Workflow vẫn chậm**
+
+- Chẩn đoán: chưa tách đủ bước độc lập để song song hóa
+- Cách sửa: xác định thêm các step có thể giao cho subagent
+
+---
+
+## Tham chiếu
+
+- **Subagent Architecture**: [subagent-architecture.md](./subagent-architecture.md)
+- **Knowledge Base System**: [knowledge-base-system.md](./knowledge-base-system.md)
+- **BMad Builder Validation Reports**: `src/workflows/testarch/*/validation-report-*.md`
+- **TEA Workflow Examples**: `src/workflows/testarch/*/steps/*.md`
+
+## Hướng phát triển tiếp theo
+
+1. Sinh step động theo độ phức tạp workflow
+2. Cache output của step cho đầu vào giống nhau
+3. Tự chia step nhỏ hơn nếu quá phức tạp
+4. Trình chỉnh sửa step trực quan
+5. Template step tái sử dụng cho pattern phổ biến
+
+---
+
+**Trạng thái**: sẵn sàng cho production
+**Validation**: 9 workflow đạt điểm tuyệt đối trên BMad Builder validation
+**Kiểm thử**: đã được thử trên dự án thật
+**Bước tiếp theo**: tiếp tục áp dụng subagent pattern ở các workflow phù hợp
diff --git a/docs/vi-vn/explanation/subagent-architecture.md b/docs/vi-vn/explanation/subagent-architecture.md
new file mode 100644
index 0000000..422036c
--- /dev/null
+++ b/docs/vi-vn/explanation/subagent-architecture.md
@@ -0,0 +1,186 @@
+---
+title: Kiến trúc subagent
+description: Cách TEA dùng subagent và agent team trong các workflow
+---
+
+# Kiến trúc subagent và agent team trong TEA
+
+Tài liệu này giải thích cách TEA điều phối công việc khi một workflow có thể tách thành các worker step độc lập hoặc các đơn vị công việc có phụ thuộc.
+
+## Phạm vi áp dụng
+
+Áp dụng cho các workflow:
+
+- `automate`
+- `atdd`
+- `test-review`
+- `nfr-assess`
+- `framework`
+- `ci`
+- `test-design`
+- `trace`
+
+Không áp dụng cho `teach-me-testing`.
+
+---
+
+## Mô hình lõi
+
+TEA orchestration có 3 phần:
+
+1. Xác định execution mode, dựa trên `tea_execution_mode` và runtime probe nếu có
+2. Dispatch worker steps, có thể độc lập hoặc có thứ tự phụ thuộc
+3. Aggregate output của worker thành artifact cuối cùng có tính xác định
+
+Worker được cô lập với nhau và trao đổi dữ liệu qua output có cấu trúc để bước aggregate có thể validate.
+
+## Execution modes
+
+TEA hỗ trợ 4 mode:
+
+- `auto`
+- `agent-team`
+- `subagent`
+- `sequential`
+
+### Ý nghĩa từng mode
+
+- `auto`: chọn mode tốt nhất runtime hỗ trợ
+- `agent-team`: ưu tiên orchestration theo team/delegation
+- `subagent`: ưu tiên worker cô lập
+- `sequential`: chạy tuần tự từng bước
+
+### Fallback behavior
+
+Khi `tea_capability_probe: true`:
+
+- `auto` fallback theo thứ tự `agent-team -> subagent -> sequential`
+- `agent-team` hoặc `subagent` có thể rơi về mode khả dụng tiếp theo
+- `sequential` luôn giữ nguyên tuần tự
+
+Khi `tea_capability_probe: false`, TEA tôn trọng mode yêu cầu nghiêm ngặt hơn và có thể fail nếu runtime không hỗ trợ.
+
+### Runtime scheduling
+
+Trong `agent-team` và `subagent`, runtime quyết định mức song song và lịch chạy. TEA không tự áp trần worker song song riêng.
+
+## Override bằng câu lệnh người dùng
+
+Trong một lần chạy, cách người dùng diễn đạt có thể override config cho đúng lần đó.
+
+Các từ được normalize:
+
+- `agent team`, `agent teams`, `agentteam` → `agent-team`
+- `subagent`, `subagents`, `sub agent` → `subagent`
+- `sequential` → `sequential`
+- `auto` → `auto`
+
+Thứ tự ưu tiên:
+
+1. Yêu cầu explicit ở lần chạy hiện tại
+2. `tea_execution_mode` trong config
+3. Runtime fallback nếu bật probing
+
+## Bản đồ áp dụng theo workflow
+
+### `automate`
+
+- Tách worker: sinh API test và E2E/backend test
+- Aggregate: gộp test sinh ra, fixture và số liệu tóm tắt
+- Mode chỉ đổi orchestration style, không đổi output contract
+
+### `atdd`
+
+- Tách worker: sinh failing API tests và failing E2E tests
+- Aggregate: kiểm tra output red-phase và gộp artifact
+
+### `test-review`
+
+- Tách worker theo từng quality dimension như determinism, isolation, maintainability, performance
+- Aggregate: tính score và report chung
+
+### `nfr-assess`
+
+- Tách worker cho security, performance, reliability, scalability
+- Aggregate: tổng hợp risk, compliance summary và priority actions
+
+### `framework`
+
+- Tách worker cho scaffold cấu trúc, config, fixture, sample
+- Aggregate: gộp các đầu ra setup
+
+### `ci`
+
+- Có khả năng dùng orchestration mode khi sinh pipeline
+- Artifact cuối vẫn là một pipeline mang tính xác định
+
+### `test-design`
+
+- Có thể chia thành work unit phục vụ sinh output thiết kế
+- Schema đầu ra không đổi theo mode
+
+### `trace`
+
+- Tách theo phase hoặc work unit có phụ thuộc
+- Aggregate coverage, gap analysis và gate data
+
+## Các guarantee về thiết kế
+
+TEA giữ nguyên các guarantee này ở mọi mode:
+
+- cùng output schema cho một workflow
+- cùng logic validate và aggregate
+- cùng semantics fallback có tính xác định
+- cùng failure behavior khi worker output thiếu hoặc không hợp lệ
+
+Mode chỉ đổi cách điều phối, không đổi hợp đồng đầu ra.
+
+## Hướng dẫn thực hành
+
+**Khuyến nghị mặc định:**
+
+```yaml
+tea_execution_mode: 'auto'
+tea_capability_probe: true
+```
+
+Dùng `sequential` khi:
+
+- cần debug rõ từng bước
+- cần chạy một luồng đơn
+- muốn đơn giản hóa troubleshooting
+
+Dùng explicit `agent-team` hoặc `subagent` khi:
+
+- bạn cố ý muốn mode đó
+- hiểu runtime hiện tại có hỗ trợ hay không
+
+## Tín hiệu troubleshooting
+
+Các nguyên nhân gây nhầm lẫn thường gặp:
+
+- có explicit override ở lần chạy hiện tại
+- runtime không hỗ trợ mode được yêu cầu nên phải fallback
+- probe bị tắt trong khi mode explicit không khả dụng
+
+Hãy kiểm tra log resolved mode trong execution report để biết workflow thực sự đã chạy bằng mode nào.
+
+## Điều này quan trọng thế nào với QC
+
+Với QC, subagent architecture quan trọng vì:
+
+- giải thích vì sao cùng một workflow có thể chạy nhanh hơn ở môi trường hỗ trợ delegation
+- giúp hiểu output vẫn nên nhất quán dù orchestration thay đổi
+- hỗ trợ debug khi report cuối cùng có dấu hiệu thiếu artifact từ một worker
+
+## Tài liệu liên quan
+
+- [Kiến trúc step-file](/docs/vi-vn/explanation/step-file-architecture.md)
+- [TEA overview](/docs/vi-vn/explanation/tea-overview.md)
+- [Cách chạy automate](/docs/vi-vn/how-to/workflows/run-automate.md)
+- [Cách chạy atdd](/docs/vi-vn/how-to/workflows/run-atdd.md)
+- [Cách chạy trace](/docs/vi-vn/how-to/workflows/run-trace.md)
+
+## Kết luận
+
+Subagent architecture cho phép TEA song song hóa phần việc khi có thể, nhưng vẫn giữ output contract ổn định. Đó là điểm quan trọng để tăng tốc mà không đánh đổi tính nhất quán của artifact đầu ra.
diff --git a/docs/vi-vn/explanation/tea-overview.md b/docs/vi-vn/explanation/tea-overview.md
new file mode 100644
index 0000000..9e72db6
--- /dev/null
+++ b/docs/vi-vn/explanation/tea-overview.md
@@ -0,0 +1,177 @@
+---
+title: 'Tổng quan Test Architect (TEA)'
+description: Hiểu agent Test Architect (TEA) và vai trò của nó trong BMad Method
+---
+
+Test Architect (TEA) là agent chuyên biệt tập trung vào chiến lược chất lượng, test automation và release gate trong các dự án BMad Method.
+
+:::tip[Triết lý thiết kế]
+TEA được xây dựng để giải quyết tình trạng AI-generated tests xuống cấp khi bước vào review. Với bài toán gốc và các nguyên tắc thiết kế, xem [Testing as Engineering](/docs/vi-vn/explanation/testing-as-engineering.md). Nếu cần thiết lập ban đầu, xem [Setup Test Framework](/docs/vi-vn/how-to/workflows/setup-test-framework.md).
+:::
+
+## Tổng quan
+
+- **Persona:** Murat, Master Test Architect và Quality Advisor, tập trung vào risk-based testing, fixture architecture, ATDD và CI/CD governance.
+- **Sứ mệnh:** cung cấp chiến lược chất lượng có thể hành động, độ phủ automation và gate decision có thể mở rộng theo độ phức tạp dự án cũng như yêu cầu compliance.
+- **Khi nào nên dùng:** dự án theo BMad Method hoặc Enterprise track, có integration risk không nhỏ, có brownfield regression risk, hoặc cần bằng chứng cho compliance/NFR. Quick Flow thường không cần TEA.
+
+## Chọn mô hình engagement của TEA
+
+BMad không bắt buộc phải dùng TEA. Có 5 cách hợp lệ để dùng, hoặc bỏ qua, TEA. Hãy chọn một cách có chủ đích.
+
+1. **Không dùng TEA**
+ - Bỏ qua toàn bộ workflow của TEA và tiếp tục với cách tiếp cận kiểm thử hiện có của đội.
+
+2. **TEA Solo (độc lập)**
+ - Dùng TEA trên một dự án không theo BMad. Bạn cần tự cung cấp requirements, spec, system-of-record pointer, hoặc source tree có thể phân tích, kèm môi trường cần thiết.
+ - Chuỗi thường gặp: `test-design` (mức hệ thống hoặc epic) -> `atdd` và/hoặc `automate` -> `test-review` tùy chọn -> `trace` để kiểm tra coverage và gate decision.
+ - Chỉ chạy `framework` hoặc `ci` nếu muốn TEA scaffold test harness hoặc pipeline; hai workflow này hiệu quả nhất khi bạn đã chốt stack/architecture.
+
+**TEA Lite (cách tiếp cận cho người mới):**
+
+- Cách đơn giản nhất để dùng TEA là chỉ dùng `automate` để kiểm thử feature hiện có.
+- Phù hợp để học nền tảng TEA trong khoảng 30 phút.
+- Xem [TEA Lite Quickstart Tutorial](/docs/vi-vn/tutorials/tea-lite-quickstart.md).
+
+**TEA Academy (lộ trình học):**
+
+- Trợ lý học tập tương tác, dạy kiểm thử tăng tiến qua 7 buổi có cấu trúc.
+- Phù hợp cho QA, developer đang học testing, hoặc bất kỳ ai muốn có nền tảng testing toàn diện.
+- **Thời lượng:** tự học trong 1-2 tuần, mỗi buổi khoảng 30-90 phút.
+- **Tính năng:** lưu trạng thái để tạm dừng/tiếp tục, ví dụ điều chỉnh theo vai trò (QA/Dev/Lead/VP), quiz validation và chứng nhận hoàn thành.
+- **Lệnh:** `teach-me-testing` hoặc `TMT` trong TEA agent.
+- Xem [Learn Testing with TEA Academy Tutorial](/docs/vi-vn/tutorials/learn-testing-tea-academy.md).
+
+3. **Tích hợp: Greenfield - BMad Method (công việc đơn giản/chuẩn)**
+ - Phase 3: `test-design` mức hệ thống, sau đó `framework` và `ci`.
+ - Phase 4: `test-design` theo từng epic, có thể thêm `atdd`, sau đó `automate` và `test-review` tùy chọn.
+ - Gate (Phase 2): `trace`.
+
+4. **Tích hợp: Brownfield - BMad Method hoặc Enterprise (đơn giản hoặc phức tạp)**
+ - Phase 2: chạy `trace` để lấy baseline.
+ - Phase 3: `test-design` mức hệ thống, sau đó `framework` và `ci`.
+ - Phase 4: `test-design` theo từng epic, tập trung vào regression và integration risk.
+ - Gate (Phase 2): `trace`; thêm `nfr-assess` nếu chưa làm trước đó.
+ - Với brownfield BMad Method, đi cùng luồng này nhưng `nfr-assess` là tùy chọn.
+
+5. **Tích hợp: Greenfield - Enterprise Method (công việc enterprise/compliance)**
+ - Phase 2: `nfr-assess`.
+ - Phase 3: `test-design` mức hệ thống, sau đó `framework` và `ci`.
+ - Phase 4: `test-design` theo epic, cộng với `atdd`/`automate`/`test-review`.
+ - Gate (Phase 2): `trace`; lưu trữ artifact khi cần.
+
+Nếu chưa chắc nên chọn mô hình nào, hãy mặc định dùng integrated path phù hợp với track hiện tại rồi điều chỉnh sau.
+
+## Danh mục lệnh của TEA
+
+| Command | Đầu ra chính | Ghi chú | Với Browser Automation (CLI/MCP) |
+| ------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `framework` | scaffold Playwright/Cypress, `.env.example`, `.nvmrc`, sample spec | Dùng khi chưa có harness ở mức production-ready | - |
+| `ci` | workflow CI, selective test script, checklist secrets | Có nhận biết nền tảng, GitHub Actions là mặc định | - |
+| `test-design` | đánh giá rủi ro, mitigation plan và coverage strategy | Risk scoring + chế độ exploratory tùy chọn | **+ Exploratory**: khám phá UI bằng browser automation để xác nhận chức năng thật |
+| `atdd` | scaffold acceptance test ở red phase + implementation checklist | Pha đỏ của TDD + recording mode tùy chọn | **+ Recording**: xác minh UI selector bằng browser thật; API test hưởng lợi từ trace analysis |
+| `automate` | spec ưu tiên, fixture, cập nhật README/script, DoD summary | Có healing/recording tùy chọn, tránh duplicate coverage | **+ Healing**: visual debugging + trace analysis để sửa test; **+ Recording**: xác minh selector (UI) + kiểm tra network (API) |
+| `test-review` | báo cáo chất lượng test với điểm 0-100, vi phạm và hướng sửa | Review test theo pattern trong knowledge base | - |
+| `nfr-assess` | báo cáo đánh giá NFR kèm hành động | Tập trung vào security/performance/reliability | - |
+| `trace` | Phase 1: coverage matrix và recommendation. Phase 2: gate decision (`PASS`/`CONCERNS`/`FAIL`/`WAIVED`) | Workflow hai phase: traceability + gate decision | - |
+
+## Vòng đời workflow của TEA
+
+**Ghi chú về cách đánh số phase:** BMad dùng phương pháp 4 phase, có thể có thêm Phase 1 tùy chọn và một prerequisite về tài liệu:
+
+- **Documentation** (tùy chọn với brownfield): prerequisite qua `document-project`
+- **Phase 1** (tùy chọn): Discovery/Analysis (`brainstorm`, `research`, `product-brief`)
+- **Phase 2** (bắt buộc): Planning (`prd` tạo PRD với FR/NFR)
+- **Phase 3** (phụ thuộc track): Solutioning (`architecture` -> `test-design` mức hệ thống -> `create-epics-and-stories` -> TEA: `framework`, `ci` -> `implementation-readiness`)
+- **Phase 4** (bắt buộc): Implementation (`sprint-planning` -> theo từng epic: `test-design` -> theo từng story: dev workflows)
+
+TEA tích hợp vào vòng đời phát triển BMad chủ yếu ở Solutioning (Phase 3) và Implementation (Phase 4):
+
+**Các workflow TEA:** `framework` và `ci` chạy một lần ở Phase 3 sau khi có architecture. `test-design` là workflow **hai chế độ**:
+
+- **System-level (Phase 3):** chạy ngay sau khi soạn architecture/ADR để tạo HAI tài liệu: `test-design-architecture.md` (cho team Architecture/Dev: testability gaps, ASR, yêu cầu NFR) và `test-design-qa.md` (cho QA: execution recipe, coverage plan, Sprint 0 setup). Các tài liệu này feed vào implementation-readiness gate.
+- **Epic-level (Phase 4):** chạy cho từng epic để tạo `test-design-epic-N.md` (risk, priority, coverage plan).
+
+Quick Flow bỏ qua Phase 1 và Phase 3.
+BMad Method và Enterprise dùng toàn bộ các phase theo nhu cầu dự án.
+Khi có ADR hoặc architecture draft, hãy chạy `test-design` ở chế độ **system-level** trước implementation-readiness gate. Cách này đảm bảo ADR có review về testability và mapping giữa ADR với test. Nếu ADR thay đổi, cần cập nhật lại test design.
+
+## Vì sao TEA khác các agent BMad khác
+
+TEA trải qua nhiều phase (Phase 3, Phase 4 và release gate), trong khi đa số agent BMM chỉ hoạt động trong một phase. Vai trò đa phase đó được ghép với một knowledge base kiểm thử riêng để giữ tiêu chuẩn nhất quán giữa các dự án.
+
+### 8 workflow của TEA theo phase
+
+| Phase | TEA workflows | Tần suất | Mục đích |
+| ----------- | --------------------------------------------------------- | ----------------- | --------------------------------------------------------- |
+| **Phase 2** | (không có workflow lõi cố định) | - | Giai đoạn planning, PM định nghĩa requirements |
+| **Phase 3** | `test-design` (system-level), `framework`, `ci` | Một lần mỗi dự án | Review testability hệ thống và thiết lập hạ tầng test |
+| **Phase 4** | `test-design`, `atdd`, `automate`, `test-review`, `trace` | Theo epic/story | Lập kế hoạch test theo epic, rồi kiểm thử theo từng story |
+| **Release** | `nfr-assess`, `trace` (Phase 2: gate) | Theo epic/release | Quyết định go/no-go |
+
+**Lưu ý:** `trace` là workflow hai phase: Phase 1 là traceability, Phase 2 là gate decision. Cách này giúp giảm cognitive load mà vẫn giữ được luồng tự nhiên.
+
+### Vì sao TEA cần knowledge base riêng
+
+TEA cần riêng:
+
+- **Kiến thức domain sâu:** test patterns, CI/CD, fixture và thực hành chất lượng
+- **Cross-cutting concerns:** các chuẩn áp dụng xuyên nhiều dự án BMad, không chỉ riêng PRD hay story
+- **Tích hợp tùy chọn:** Playwright Utils, Playwright CLI và mở rộng qua MCP
+
+Kiến trúc này cho phép TEA duy trì testing patterns ở mức production-ready trong khi vẫn hoạt động xuyên nhiều phase.
+
+## Cheat sheet theo track
+
+Những cheat sheet này ánh xạ workflow của TEA vào **BMad Method và Enterprise tracks** trên **phương pháp 4 phase** (Phase 1: Analysis, Phase 2: Planning, Phase 3: Solutioning, Phase 4: Implementation).
+
+**Lưu ý:** Quick Flow thường không cần TEA. Các cheat sheet dưới đây tập trung vào BMad Method và Enterprise, nơi TEA tạo ra giá trị rõ rệt hơn.
+
+### Greenfield - BMad Method
+
+**Use case:** dự án mới với độ phức tạp tiêu chuẩn
+
+- Phase 2: PM tạo PRD
+- Phase 3: `architecture` -> `test-design` mức hệ thống -> `framework` -> `ci`
+- Phase 4: `test-design` theo epic -> `atdd` tùy chọn -> `automate` -> `test-review`/`trace`
+- Release gate: `trace` và `test-review` tùy chọn
+
+### Brownfield - BMad Method hoặc Enterprise
+
+**Use case:** codebase hiện có
+
+Các khác biệt chính so với greenfield:
+
+- Có thể cần `document-project` trước
+- Thêm baseline `trace` ngay từ đầu
+- `test-design` tập trung vào hotspot và regression
+- Có thể cần `nfr-assess` trong story review hoặc release gate
+
+### Enterprise
+
+Điểm nhấn bổ sung:
+
+- `nfr-assess` quan trọng hơn
+- Yêu cầu lưu artifact và bằng chứng chặt hơn
+- Gate decision thường gắn với compliance hơn là chỉ functional readiness
+
+## Điều này quan trọng thế nào với QC
+
+Với QC, TEA không chỉ là agent sinh test. Nó là lớp điều phối chất lượng:
+
+- Giúp lập kế hoạch test theo rủi ro
+- Giúp sinh và review test theo chuẩn
+- Giúp nối coverage với requirement và release gate
+- Giúp biến quality từ hoạt động cảm tính thành artifact kỹ thuật có thể viện dẫn
+
+## Tài liệu liên quan
+
+- [Engagement Models](/docs/vi-vn/explanation/engagement-models.md)
+- [Risk-Based Testing](/docs/vi-vn/explanation/risk-based-testing.md)
+- [Knowledge Base System](/docs/vi-vn/explanation/knowledge-base-system.md)
+- [Cách thiết lập test framework](/docs/vi-vn/how-to/workflows/setup-test-framework.md)
+- [Cách chạy trace](/docs/vi-vn/how-to/workflows/run-trace.md)
+
+## Kết luận
+
+TEA là lớp chuyên môn chất lượng của BMad Method. Giá trị lớn nhất của nó nằm ở việc nối liền planning, implementation và release gate bằng cùng một hệ chuẩn testing và cùng một chuỗi artifact có thể kiểm chứng.
diff --git a/docs/vi-vn/explanation/test-quality-standards.md b/docs/vi-vn/explanation/test-quality-standards.md
new file mode 100644
index 0000000..30eacfe
--- /dev/null
+++ b/docs/vi-vn/explanation/test-quality-standards.md
@@ -0,0 +1,480 @@
+---
+title: 'Giải thích tiêu chuẩn chất lượng test'
+description: Hiểu Definition of Done của TEA cho các test có tính xác định, cô lập và dễ bảo trì
+---
+
+# Giải thích tiêu chuẩn chất lượng test
+
+Tiêu chuẩn chất lượng test định nghĩa điều gì làm nên một test "tốt" trong TEA. Đây không phải là gợi ý tùy chọn, mà là **Definition of Done** để ngăn test bị mục trong quá trình review.
+
+## Tổng quan
+
+**Các nguyên tắc chất lượng của TEA:**
+
+- **Deterministic** - cùng đầu vào, cùng kết quả ở mọi lần chạy
+- **Isolated** - không phụ thuộc test khác
+- **Explicit** - assertion hiện rõ trong thân test
+- **Focused** - phạm vi phù hợp, một trách nhiệm chính
+- **Fast** - chạy trong thời gian hợp lý
+
+Nếu test vi phạm những nguyên tắc này, nó tạo gánh nặng bảo trì, làm chậm phát triển và khiến cả team mất niềm tin vào suite.
+
+## Vấn đề
+
+### Test bị "mục" ngay trong vòng review
+
+```typescript
+test('user can do stuff', async ({ page }) => {
+ await page.goto('/');
+ await page.waitForTimeout(5000);
+
+ if (await page.locator('.banner').isVisible()) {
+ await page.click('.dismiss');
+ }
+
+ try {
+ await page.click('#load-more');
+ } catch (e) {
+ // Bỏ qua lỗi
+ }
+
+ // ... thêm 300 dòng logic
+});
+```
+
+**Các vấn đề chính:**
+
+- Hard wait gây flaky
+- Điều kiện `if/else` làm hành vi không còn xác định
+- `try/catch` che mất failure
+- Test quá lớn, khó hiểu
+- Tên mơ hồ
+- Assertion không rõ đang kiểm tra điều gì
+
+Kết quả là PR review sẽ nhận comment kiểu "test này flaky, sửa rồi quay lại", rồi cuối cùng test không được merge hoặc bị xóa.
+
+### AI sinh test nhưng không có quality guardrail
+
+Không có chuẩn chất lượng, AI rất dễ sinh ra hàng loạt test kiểu:
+
+```typescript
+test('test1', async ({ page }) => {
+ await page.goto('/');
+ await page.waitForTimeout(3000);
+});
+
+test('test2', async ({ page }) => {
+ await page.goto('/');
+ await page.waitForTimeout(3000);
+});
+```
+
+Kết quả là có thể có 50 test, nhưng phần lớn bị trùng, flaky và không ai dám tin.
+
+## Lời giải: các tiêu chuẩn chất lượng của TEA
+
+### 1. Determinism, không flaky
+
+**Quy tắc:** test phải cho cùng kết quả ở mọi lần chạy.
+
+**Yêu cầu:**
+
+- Không dùng hard wait như `waitForTimeout`
+- Không dùng `if/else` để điều khiển flow chính
+- Không dùng `try/catch` để nuốt lỗi
+- Dùng network-first patterns
+- Dùng explicit wait như `waitForResponse`, `waitForSelector`
+
+**Ví dụ xấu:**
+
+```typescript
+test('flaky test', async ({ page }) => {
+ await page.click('button');
+ await page.waitForTimeout(2000);
+
+ if (await page.locator('.modal').isVisible()) {
+ await page.click('.dismiss');
+ }
+
+ try {
+ await expect(page.locator('.success')).toBeVisible();
+ } catch (e) {
+ // Test vẫn pass dù assertion fail
+ }
+});
+```
+
+**Ví dụ tốt với Playwright:**
+
+```typescript
+test('deterministic test', async ({ page }) => {
+ const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/submit') && resp.ok());
+
+ await page.click('button');
+ await responsePromise;
+
+ await expect(page.locator('.modal')).toBeVisible();
+ await page.click('.dismiss');
+ await expect(page.locator('.success')).toBeVisible();
+});
+```
+
+**Với Playwright Utils:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+import { expect } from '@playwright/test';
+
+test('deterministic test', async ({ page, interceptNetworkCall }) => {
+ const submitCall = interceptNetworkCall({
+ method: 'POST',
+ url: '**/api/submit',
+ });
+
+ await page.click('button');
+
+ const { status, responseJson } = await submitCall;
+ expect(status).toBe(200);
+
+ await expect(page.locator('.modal')).toBeVisible();
+ await page.click('.dismiss');
+ await expect(page.locator('.success')).toBeVisible();
+});
+```
+
+### 2. Isolation, không phụ thuộc test khác
+
+**Quy tắc:** mỗi test phải chạy độc lập.
+
+**Yêu cầu:**
+
+- Tự dọn dẹp dữ liệu
+- Không phụ thuộc global state
+- Có thể chạy song song
+- Có thể chạy theo bất kỳ thứ tự nào
+- Dùng dữ liệu test duy nhất
+
+**Ví dụ xấu:**
+
+```typescript
+let userId: string;
+
+test('create user', async ({ apiRequest }) => {
+ const { body } = await apiRequest({
+ method: 'POST',
+ path: '/api/users',
+ body: { email: 'test@example.com' },
+ });
+ userId = body.id;
+});
+
+test('update user', async ({ apiRequest }) => {
+ await apiRequest({
+ method: 'PATCH',
+ path: `/api/users/${userId}`,
+ body: { name: 'Updated' },
+ });
+});
+```
+
+**Vì sao không ổn:**
+
+- Thứ tự chạy trở thành bắt buộc
+- `.only` hoặc skip một test sẽ làm test khác hỏng
+- Dữ liệu hard-code dễ va chạm
+- Không cleanup
+
+**Ví dụ tốt với request API thuần:**
+
+```typescript
+test('should update user profile', async ({ request }) => {
+ const testEmail = `test-${Date.now()}@example.com`;
+
+ const createResp = await request.post('/api/users', {
+ data: { email: testEmail, name: 'Original' },
+ });
+ const user = await createResp.json();
+
+ const updateResp = await request.patch(`/api/users/${user.id}`, {
+ data: { name: 'Updated' },
+ });
+ const updated = await updateResp.json();
+
+ expect(updated.name).toBe('Updated');
+
+ await request.delete(`/api/users/${user.id}`);
+});
+```
+
+**Ví dụ tốt hơn với Playwright Utils:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { expect } from '@playwright/test';
+import { faker } from '@faker-js/faker';
+
+test('should update user profile', async ({ apiRequest }) => {
+ const testEmail = faker.internet.email();
+
+ const { status: createStatus, body: user } = await apiRequest({
+ method: 'POST',
+ path: '/api/users',
+ body: { email: testEmail, name: faker.person.fullName() },
+ });
+
+ expect(createStatus).toBe(201);
+
+ const { status, body: updated } = await apiRequest({
+ method: 'PATCH',
+ path: `/api/users/${user.id}`,
+ body: { name: 'Updated Name' },
+ });
+
+ expect(status).toBe(200);
+ expect(updated.name).toBe('Updated Name');
+
+ await apiRequest({
+ method: 'DELETE',
+ path: `/api/users/${user.id}`,
+ });
+});
+```
+
+**Điểm mạnh của Playwright Utils ở đây:**
+
+- Trả về `{ status, body }` gọn hơn
+- Không cần tự `await response.json()`
+- Có retry tự động cho một số lỗi 5xx
+- Có thể nối `.validateSchema()` khi cần
+
+### 3. Explicit assertions, không giấu validation
+
+**Quy tắc:** assertion phải nhìn thấy trực tiếp trong test body.
+
+**Yêu cầu:**
+
+- Assertion nằm trong test, không chôn trong helper
+- Assertion cụ thể
+- Kỳ vọng có ý nghĩa nghiệp vụ
+
+**Ví dụ xấu:**
+
+```typescript
+async function verifyProfilePage(page: Page) {
+ await expect(page.locator('h1')).toBeVisible();
+ await expect(page.locator('.email')).toContainText('@');
+ await expect(page.locator('.name')).not.toBeEmpty();
+}
+
+test('profile page', async ({ page }) => {
+ await page.goto('/profile');
+ await verifyProfilePage(page);
+});
+```
+
+Vấn đề là người review không nhìn test là biết nó đang xác minh điều gì.
+
+**Ví dụ tốt:**
+
+```typescript
+test('should display profile with correct data', async ({ page }) => {
+ await page.goto('/profile');
+
+ await expect(page.locator('h1')).toContainText('Test User');
+ await expect(page.locator('.email')).toContainText('test@example.com');
+ await expect(page.locator('.bio')).toContainText('Software Engineer');
+ await expect(page.locator('img[alt=\"Avatar\"]')).toBeVisible();
+});
+```
+
+**Ngoại lệ hợp lý:** helper dùng cho setup và cleanup, không phải để giấu assertion chính.
+
+### 4. Focused tests, phạm vi hợp lý
+
+**Quy tắc:** một test nên có một trách nhiệm chính và kích thước hợp lý.
+
+**Yêu cầu:**
+
+- Kích thước dưới khoảng 300 dòng
+- Một trách nhiệm chính
+- `describe` và `test` đặt tên rõ
+- Phạm vi vừa đủ, không quá rộng cũng không quá vụn
+
+**Ví dụ xấu:**
+
+```typescript
+test('complete user flow', async ({ page }) => {
+ // Registration
+ // Profile setup
+ // Settings configuration
+ // Data export
+ // Tổng cộng 500 dòng
+});
+```
+
+Vấn đề là failure ở dòng đầu có thể chặn luôn phần còn lại, khó debug và khó review.
+
+**Ví dụ tốt:**
+
+```typescript
+test('should register new user', async ({ page }) => {
+ await page.goto('/register');
+ await page.fill('#email', 'test@example.com');
+ await page.fill('#password', 'password123');
+ await page.click('button[type=\"submit\"]');
+
+ await expect(page).toHaveURL('/welcome');
+ await expect(page.locator('h1')).toContainText('Welcome');
+});
+
+test('should configure user profile', async ({ page, authSession }) => {
+ await authSession.login({ email: 'test@example.com', password: 'pass' });
+ await page.goto('/profile');
+
+ await page.fill('#name', 'Test User');
+ await page.fill('#bio', 'Software Engineer');
+ await page.click('button:has-text(\"Save\")');
+
+ await expect(page.locator('.success')).toBeVisible();
+});
+```
+
+### 5. Fast execution, có ngân sách hiệu năng
+
+**Quy tắc:** một test đơn lẻ nên chạy trong khoảng dưới 1.5 phút.
+
+**Yêu cầu:**
+
+- Thời gian chạy dưới 90 giây
+- Selector hiệu quả, ưu tiên `getByRole`
+- Hạn chế thao tác thừa
+- Có thể chạy song song
+
+**Ví dụ xấu:**
+
+```typescript
+test('slow test', async ({ page }) => {
+ await page.goto('/');
+ await page.waitForTimeout(10000);
+
+ for (let i = 1; i <= 10; i++) {
+ await page.click(`a[href=\"/page-${i}\"]`);
+ await page.waitForTimeout(5000);
+ }
+
+ await page.locator('//div[@class=\"container\"]/section[3]/div[2]/p').click();
+ await page.waitForTimeout(30000);
+ await expect(page.locator('.result')).toBeVisible();
+});
+```
+
+**Ví dụ tốt với Playwright:**
+
+```typescript
+test('fast test', async ({ page }) => {
+ const apiPromise = page.waitForResponse((resp) => resp.url().includes('/api/result') && resp.ok());
+
+ await page.goto('/');
+ await page.goto('/page-10');
+ await page.getByRole('button', { name: 'Submit' }).click();
+ await apiPromise;
+
+ await expect(page.locator('.result')).toBeVisible();
+});
+```
+
+**Ví dụ với Playwright Utils:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+import { expect } from '@playwright/test';
+
+test('fast test', async ({ page, interceptNetworkCall }) => {
+ const resultCall = interceptNetworkCall({
+ method: 'GET',
+ url: '**/api/result',
+ });
+
+ await page.goto('/');
+ await page.goto('/page-10');
+ await page.getByRole('button', { name: 'Submit' }).click();
+
+ const { status, responseJson } = await resultCall;
+ expect(status).toBe(200);
+ await expect(page.locator('.result')).toBeVisible();
+});
+```
+
+## Cách TEA áp tiêu chuẩn này
+
+TEA dùng các tiêu chuẩn này như một thước đo review và một điều kiện hoàn thành khi sinh test:
+
+- `atdd` và `automate` dùng chúng để sinh test đúng chuẩn ngay từ đầu
+- `test-review` dùng chúng để audit test hiện có
+- `framework` scaffold cấu trúc hỗ trợ deterministic và isolation
+
+## Anti-patterns TEA đặc biệt không chấp nhận
+
+### Hard waits
+
+```typescript
+await page.waitForTimeout(3000);
+```
+
+### Flow control bằng conditional
+
+```typescript
+if (await page.locator('.toast').isVisible()) {
+ await page.click('.toast-close');
+}
+```
+
+### Nuốt lỗi bằng try/catch
+
+```typescript
+try {
+ await expect(page.locator('.success')).toBeVisible();
+} catch (e) {}
+```
+
+### Assertion mơ hồ
+
+```typescript
+expect(value).toBeTruthy();
+```
+
+### Test ôm quá nhiều trách nhiệm
+
+Một test vừa đăng ký, vừa thanh toán, vừa export dữ liệu thường là dấu hiệu cần tách.
+
+## Vì sao điều này quan trọng với QC
+
+Đối với QC, các tiêu chuẩn này biến suite từ "có vẻ chạy được" thành "có thể vận hành và bảo trì":
+
+- Giảm flaky thật sự, không chỉ che đi
+- Review có tiêu chí khách quan hơn
+- Dễ truy nguyên lỗi hơn khi test fail
+- Tăng khả năng dùng CI làm quality gate
+
+## Tài liệu liên quan
+
+- [Network-first patterns](/docs/vi-vn/explanation/network-first-patterns.md)
+- [Fixture architecture](/docs/vi-vn/explanation/fixture-architecture.md)
+- [Knowledge base system](/docs/vi-vn/explanation/knowledge-base-system.md)
+- [Cách chạy test-review](/docs/vi-vn/how-to/workflows/run-test-review.md)
+- [Cách chạy ATDD](/docs/vi-vn/how-to/workflows/run-atdd.md)
+- [Cách chạy automate](/docs/vi-vn/how-to/workflows/run-automate.md)
+
+## Kết luận
+
+Một test đạt chuẩn trong TEA không chỉ là test pass. Nó phải:
+
+- ổn định
+- độc lập
+- minh bạch
+- đúng phạm vi
+- đủ nhanh để team còn muốn giữ nó lại
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/explanation/testing-as-engineering.md b/docs/vi-vn/explanation/testing-as-engineering.md
new file mode 100644
index 0000000..f310b55
--- /dev/null
+++ b/docs/vi-vn/explanation/testing-as-engineering.md
@@ -0,0 +1,85 @@
+---
+title: 'Kiểm thử như một hoạt động kỹ thuật'
+description: Vì sao TEA xem kiểm thử là công việc kỹ thuật có thiết kế, có kiến trúc và có tiêu chuẩn vận hành
+---
+
+# Kiểm thử như một hoạt động kỹ thuật
+
+TEA được xây dựng trên quan điểm rằng kiểm thử không chỉ là viết case hay chạy regression, mà là một hoạt động kỹ thuật có mục tiêu, có thiết kế và có tiêu chuẩn chất lượng.
+
+## Vấn đề TEA muốn giải quyết
+
+Nhiều bộ test do AI hoặc do đội dự án tạo nhanh thường gặp các vấn đề:
+
+- Phụ thuộc mạnh vào UI và selector dễ vỡ
+- Không có chiến lược ưu tiên theo rủi ro
+- Chạy không ổn định, nhiều flaky test
+- Trùng lặp coverage nhưng vẫn bỏ sót lỗ hổng quan trọng
+- Khó review, khó truy vết và khó dùng cho gate release
+
+TEA giải quyết các vấn đề này bằng cách chuẩn hóa cách thiết kế, tổ chức và đánh giá test.
+
+## Các nguyên tắc cốt lõi
+
+### 1. Ưu tiên theo rủi ro
+
+Không phải mọi hành vi đều có giá trị như nhau. Những luồng có xác suất lỗi cao hoặc tác động lớn cần được ưu tiên trước bằng P0-P3.
+
+### 2. Thiết kế trước khi tự động hóa
+
+Không viết test trước khi hiểu hệ thống cần bao phủ cái gì. `test-design` luôn là đầu vào quan trọng cho `atdd` và `automate`.
+
+### 3. Tính ổn định quan trọng hơn số lượng
+
+Một bộ test nhỏ nhưng ổn định, có tín hiệu rõ ràng, luôn tốt hơn một bộ test lớn nhưng nhiều nhiễu và khó tin cậy.
+
+### 4. Khả năng truy vết là bắt buộc
+
+Mỗi yêu cầu, acceptance criteria hoặc rủi ro quan trọng cần có cách ánh xạ tới test, bằng chứng hoặc waiver tương ứng.
+
+### 5. Kiểm thử là một phần của kiến trúc
+
+Fixture, data factory, network strategy, selector strategy và CI pipeline đều là thành phần kiến trúc test, không phải việc bổ sung sau cùng.
+
+## TEA định nghĩa chất lượng test như thế nào
+
+Một test tốt trong TEA cần:
+
+- Có mục đích rõ ràng
+- Bao phủ đúng rủi ro
+- Dễ đọc, dễ review
+- Chạy ổn định
+- Cô lập dữ liệu và môi trường hợp lý
+- Hỗ trợ chẩn đoán khi fail
+- Có thể duy trì trong thời gian dài
+
+## Hệ quả trong thực tế cho QC
+
+Khi áp dụng TEA, đội QC thường thay đổi cách làm ở các điểm sau:
+
+- Không bắt đầu bằng “viết thật nhiều test”
+- Bắt đầu bằng phân tích rủi ro và coverage strategy
+- Xem xét testability ngay từ lúc đọc architecture hoặc PRD
+- Dùng review chất lượng test như một hoạt động kỹ thuật chính thức
+- Dùng traceability và gate để ra quyết định phát hành dựa trên bằng chứng
+
+## Cách TEA đưa nguyên tắc vào workflow
+
+- `test-design`: xác định rủi ro, vùng cần bao phủ và mức ưu tiên
+- `atdd`: tạo acceptance test ở pha đỏ trước khi code hoàn chỉnh
+- `automate`: mở rộng coverage sau implementation
+- `test-review`: kiểm tra chất lượng của chính bộ test
+- `trace`: xác nhận coverage và hỗ trợ gate decision
+- `nfr-assess`: đánh giá góc nhìn phi chức năng
+
+## Điều cần tránh
+
+- Test chỉ mô phỏng happy path
+- Chạy E2E cho mọi thứ thay vì phân tầng hợp lý
+- Phụ thuộc selector mong manh
+- Thiếu fixture và data strategy
+- Không có tiêu chí rõ ràng để PASS/FAIL release
+
+## Tóm tắt
+
+TEA xem kiểm thử là một hệ thống kỹ thuật hoàn chỉnh. Điều này đặc biệt phù hợp với QC trong môi trường enterprise, nơi độ tin cậy, khả năng review, truy vết và bằng chứng phát hành quan trọng không kém số lượng test.
diff --git a/docs/vi-vn/glossary/index.md b/docs/vi-vn/glossary/index.md
new file mode 100644
index 0000000..886f777
--- /dev/null
+++ b/docs/vi-vn/glossary/index.md
@@ -0,0 +1,115 @@
+---
+title: 'Thuật ngữ TEA'
+description: Tài liệu thuật ngữ cho Test Architect (TEA)
+---
+
+Tài liệu tham chiếu thuật ngữ cho Test Architect (TEA).
+
+## Khái niệm cốt lõi
+
+| Thuật ngữ | Định nghĩa |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| **Agent** | Persona AI chuyên biệt với chuyên môn cụ thể như PM, Architect, SM, DEV, TEA; dùng để dẫn dắt workflow và tạo deliverable. |
+| **BMad** | Breakthrough Method of Agile AI-Driven Development - framework agile do AI dẫn dắt với agent chuyên biệt và workflow có hướng dẫn. |
+| **BMad Method** | Phương pháp hoàn chỉnh cho phát triển phần mềm có AI hỗ trợ, bao gồm planning, architecture, implementation và quality workflow. |
+| **Workflow** | Quy trình nhiều bước để điều phối hoạt động của agent và tạo đầu ra cụ thể. |
+| **Context Engineering** | Cách nạp standards chuyên biệt vào AI context thông qua manifest để đầu ra ổn định hơn, ít phụ thuộc prompt wording. |
+
+## Quy mô và độ phức tạp
+
+| Thuật ngữ | Định nghĩa |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Quick Flow Track** | Track triển khai nhanh dùng tech-spec, phù hợp bug fix và thay đổi nhỏ, rõ phạm vi. |
+| **BMad Method Track** | Track planning đầy đủ dùng PRD + Architecture + UX, phù hợp sản phẩm và tính năng phức tạp hơn. |
+| **Enterprise Method Track** | Track mở rộng thêm Security Architecture, DevOps Strategy và Test Strategy, phù hợp compliance và hệ nhiều tenant. |
+| **Planning Track** | Con đường phương pháp được chọn dựa trên nhu cầu planning và độ phức tạp, không chỉ dựa vào số lượng story. |
+
+## Tài liệu planning
+
+| Thuật ngữ | Định nghĩa |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| **PRD** | Product Requirements Document, chứa vision, goals, FR, NFR và success criteria; tập trung vào cần xây cái gì. |
+| **Architecture Document** | Tài liệu thiết kế hệ thống ở mức toàn cục, mô tả cấu trúc, component, data model, integration, security và deployment. |
+| **Product Brief** | Tài liệu chiến lược tùy chọn ở giai đoạn đầu, ghi lại product vision, market context và yêu cầu cấp cao. |
+| **Tech-Spec** | Kế hoạch kỹ thuật toàn diện cho Quick Flow, bao gồm problem statement, solution approach, file-level change và testing strategy. |
+| **Epic** | Nhóm feature cấp cao chứa nhiều story liên quan với nhau. |
+
+## Workflow và phase
+
+| Thuật ngữ | Định nghĩa |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **Phase 0: Documentation** | Pha tiền điều kiện cho brownfield khi codebase thiếu tài liệu, thường dùng để document dự án hiện có. |
+| **Phase 1: Analysis** | Pha discovery gồm brainstorm, research và product brief. |
+| **Phase 2: Planning** | Pha bắt buộc tạo formal requirements, dẫn tới tech-spec hoặc PRD. |
+| **Phase 3: Solutioning** | Pha kiến trúc và readiness, nơi thường chạy architecture, system-level test-design, framework và ci. |
+| **Phase 4: Implementation** | Pha phát triển theo sprint và story, nơi diễn ra phần lớn workflow của DEV và TEA. |
+| **Gate Check** | Workflow validation để xác nhận tài liệu và readiness đã đủ trước khi chuyển sang bước tiếp theo. |
+
+## Agent và vai trò
+
+| Thuật ngữ | Định nghĩa |
+| -------------- | ---------------------------------------------------------------------------------------- |
+| **Analyst** | Agent khởi tạo workflow, làm research, tạo product brief và theo dõi tiến độ. |
+| **Architect** | Agent thiết kế kiến trúc hệ thống và validate design. |
+| **PM** | Product Manager agent tạo PRD hoặc tech-spec. |
+| **SM** | Scrum Master agent quản lý sprint, tạo story và điều phối implementation. |
+| **DEV** | Developer agent triển khai story, viết code, chạy test và review code. |
+| **TEA** | Test Architect agent chịu trách nhiệm chiến lược kiểm thử, quality gate và đánh giá NFR. |
+| **Party Mode** | Chế độ nhiều agent thảo luận cùng nhau do BMad Master điều phối. |
+
+## Trạng thái và theo dõi
+
+| Thuật ngữ | Định nghĩa |
+| ------------------- | ------------------------------------------------------------------------------------------- |
+| **DoD** | Definition of Done - tiêu chí để một story được xem là hoàn thành. |
+| **Workflow Status** | Điểm vào chung để kiểm tra file trạng thái hiện có, hiển thị tiến độ và gợi ý bước kế tiếp. |
+| **Sprint** | Khoảng thời gian phát triển cố định, thường 1-2 tuần. |
+| **Story** | Đơn vị công việc có thể triển khai với acceptance criteria rõ ràng. |
+| **Story File** | File markdown mô tả story, acceptance criteria, technical note và testing requirement. |
+
+## Test Architect (TEA) Concepts
+
+| Thuật ngữ | Định nghĩa |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| **ATDD** | Acceptance Test-Driven Development - sinh failing acceptance test trước khi implementation, tương ứng red phase của TDD. |
+| **Burn-in Testing** | Chạy test nhiều lần liên tiếp để phát hiện flaky test và lỗi ngắt quãng. |
+| **Coverage Traceability** | Ánh xạ requirement, endpoint, oracle hoặc user journey với test đã có để biết mức bao phủ là FULL, PARTIAL hay NONE. |
+| **Epic-Level Test Design** | Lập kế hoạch test cho từng epic ở Phase 4, tập trung vào risk, priority và coverage strategy của epic đó. |
+| **Fixture Architecture** | Pattern xây pure function trước, rồi bọc bằng fixture theo framework để tăng testability và tái sử dụng. |
+| **Gate Decision** | Quyết định phát hành với 4 trạng thái: `PASS`, `CONCERNS`, `FAIL`, `WAIVED`. |
+| **Knowledge Fragment** | Một file markdown đơn lẻ trong knowledge base của TEA, mô tả một pattern hoặc thực hành kiểm thử cụ thể. |
+| **Browser Automation** | Khả năng dùng Playwright CLI hoặc MCP để tương tác browser thật khi sinh hoặc chữa test. |
+| **Network-First Pattern** | Pattern chờ phản hồi network thực tế thay vì timeout cố định, giúp giảm race condition và flakiness. |
+| **NFR Assessment** | Đánh giá yêu cầu phi chức năng như security, performance, reliability bằng evidence. |
+| **Playwright Utils** | Gói tùy chọn `@seontechnologies/playwright-utils` cung cấp fixture và utility production-ready cho Playwright. |
+| **Risk-Based Testing** | Cách ưu tiên kiểm thử theo business impact bằng điểm probability × impact. |
+| **System-Level Test Design** | Lập kế hoạch test ở mức architecture trong Phase 3, tập trung vào testability, ADR mapping và nhu cầu hạ tầng test. |
+| **tea-index.csv** | File manifest theo dõi knowledge fragments, tags và workflow nào sẽ nạp chúng. |
+| **TEA Integrated** | Mô hình dùng TEA đầy đủ xuyên các phase của BMad Method. |
+| **TEA Lite** | Cách dùng TEA đơn giản nhất, chủ yếu với `automate` để test feature hiện có. |
+| **TEA Solo** | Mô hình dùng TEA độc lập ngoài full BMad Method. |
+| **Test Priorities** | Hệ thống phân loại độ quan trọng của test: P0, P1, P2, P3. |
+
+## Thuật ngữ thực dụng khác
+
+| Thuật ngữ | Định nghĩa |
+| ----------------------- | -------------------------------------------------------------------------------------- |
+| **Brownfield** | Dự án hoặc codebase đã tồn tại, có ràng buộc legacy và nguy cơ hồi quy. |
+| **Greenfield** | Dự án mới, ít hoặc không có ràng buộc legacy. |
+| **Acceptance Criteria** | Điều kiện chấp nhận xác định hành vi nào cần được xem là đúng về mặt nghiệp vụ. |
+| **E2E** | End-to-end testing, kiểm thử luồng đầu-cuối qua nhiều lớp của hệ thống. |
+| **Fixture** | Cơ chế setup/teardown hoặc cung cấp context dùng chung cho test. |
+| **Flaky Test** | Test cho kết quả không ổn định dù hệ thống không thay đổi thực sự. |
+| **Coverage** | Mức độ yêu cầu, rủi ro hoặc hành vi đã được bao phủ bởi test. |
+| **Traceability** | Khả năng nối requirement, test, evidence và gate decision thành chuỗi kiểm chứng được. |
+
+## Xem thêm
+
+- [TEA Overview](/docs/vi-vn/explanation/tea-overview.md)
+- [TEA Knowledge Base](/docs/vi-vn/reference/knowledge-base.md)
+- [TEA Command Reference](/docs/vi-vn/reference/commands.md)
+- [TEA Configuration](/docs/vi-vn/reference/configuration.md)
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org)
diff --git a/docs/vi-vn/how-to/brownfield/use-tea-for-enterprise.md b/docs/vi-vn/how-to/brownfield/use-tea-for-enterprise.md
new file mode 100644
index 0000000..46337e2
--- /dev/null
+++ b/docs/vi-vn/how-to/brownfield/use-tea-for-enterprise.md
@@ -0,0 +1,372 @@
+---
+title: 'Chạy TEA cho dự án enterprise'
+description: Dùng TEA trong môi trường enterprise có yêu cầu về compliance, security, audit và quy định pháp lý
+---
+
+# Chạy TEA cho dự án enterprise
+
+Dùng TEA cho các dự án enterprise có yêu cầu về compliance, security, audit và regulatory. Hướng dẫn này bao phủ NFR assessment, audit trail và việc thu thập evidence.
+
+## Khi nào nên dùng
+
+- Dự án thuộc enterprise track, không phải Quick Flow hay BMad Method đơn giản
+- Có yêu cầu compliance như SOC 2, HIPAA, GDPR, v.v.
+- Ứng dụng có tính chất security-critical như tài chính, y tế, chính phủ
+- Cần audit trail
+- Có threshold nghiêm ngặt cho performance, security và reliability
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method và chọn enterprise track
+- Agent TEA có sẵn
+- Yêu cầu compliance đã được tài liệu hóa
+- Đã xác định stakeholder phê duyệt gate
+
+## Workflow TEA đặc thù cho enterprise
+
+### NFR Assessment (`nfr-assess`)
+
+**Mục đích:** xác thực yêu cầu phi chức năng bằng bằng chứng.
+
+**Khi dùng:** Phase 2 (sớm) và Release Gate
+
+**Vì sao enterprise cần workflow này:**
+
+- Compliance bắt buộc threshold cụ thể
+- Audit trail là điều kiện cần cho chứng nhận
+- Security requirements không thể thương lượng
+- SLA về hiệu năng mang tính hợp đồng
+
+**Ví dụ:**
+
+```text
+nfr-assess
+
+Categories: Security, Performance, Reliability, Maintainability
+
+Security thresholds:
+- Zero critical vulnerabilities (required by SOC 2)
+- All endpoints require authentication
+- Data encrypted at rest (FIPS 140-2)
+- Audit logging on all data access
+
+Evidence:
+- Security scan: reports/nessus-scan.pdf
+- Penetration test: reports/pentest-2026-01.pdf
+- Compliance audit: reports/soc2-evidence.zip
+```
+
+**Đầu ra:** báo cáo NFR với trạng thái `PASS` / `CONCERNS` / `FAIL` cho từng category.
+
+### Trace với audit evidence (`trace`)
+
+**Mục đích:** requirements traceability kèm audit trail.
+
+**Khi dùng:** Phase 2 (baseline), Phase 4 (refresh), Release Gate
+
+**Vì sao enterprise cần workflow này:**
+
+- Auditor cần mapping từ requirement tới test
+- Chứng nhận compliance cần traceability
+- Cơ quan quản lý yêu cầu evidence
+
+**Ví dụ:**
+
+```text
+trace Phase 1
+
+Requirements: PRD.md (with compliance requirements)
+Test location: tests/
+
+Output: traceability-matrix.md with:
+- Requirement-to-test mapping
+- Compliance requirement coverage
+- Gap prioritization
+- Recommendations
+```
+
+**Cho Release Gate:**
+
+```text
+trace Phase 2
+
+Generate gate-decision-{gate_type}-{story_id}.md with:
+- Evidence references
+- Approver signatures
+- Compliance checklist
+- Decision rationale
+```
+
+### Test Design có trọng tâm compliance (`test-design`)
+
+**Mục đích:** đánh giá rủi ro với trọng tâm compliance và security.
+
+**Khi dùng:** Phase 3 (system-level), Phase 4 (epic-level)
+
+**Vì sao enterprise cần workflow này:**
+
+- Kiến trúc bảo mật phải được kiểm tra về testability
+- Compliance requirements phải có khả năng kiểm thử
+- Performance requirements mang tính hợp đồng
+
+**Ví dụ:**
+
+```text
+test-design
+
+Mode: System-level
+
+Focus areas:
+- Security architecture (authentication, authorization, encryption)
+- Performance requirements (SLA: P99 <200ms)
+- Compliance (HIPAA PHI handling, audit logging)
+
+Output: TWO documents (system-level):
+- test-design-architecture.md: Security gaps, compliance requirements, performance SLOs for Architecture team
+- test-design-qa.md: Security testing strategy, compliance test mapping, performance testing plan for QA team
+- Audit logging validation
+```
+
+## Vòng đời TEA cho enterprise
+
+### Phase 1: Discovery (tùy chọn nhưng nên có)
+
+**Nghiên cứu yêu cầu compliance sớm:**
+
+```text
+Analyst: research
+
+Topics:
+- Industry compliance (SOC 2, HIPAA, GDPR)
+- Security standards (OWASP Top 10)
+- Performance benchmarks (industry P99)
+```
+
+### Phase 2: Planning (bắt buộc)
+
+**1. Định nghĩa NFR từ sớm:**
+
+```text
+PM: prd
+
+Include in PRD:
+- Security requirements (authentication, encryption)
+- Performance SLAs (response time, throughput)
+- Reliability targets (uptime, RTO, RPO)
+- Compliance mandates (data retention, audit logs)
+```
+
+**2. Đánh giá NFR:**
+
+```text
+TEA: nfr-assess
+
+Categories: All (Security, Performance, Reliability, Maintainability)
+
+Output: nfr-assessment.md
+- NFR requirements documented
+- Acceptance criteria defined
+- Test strategy planned
+```
+
+**3. Baseline (chỉ với brownfield):**
+
+```text
+TEA: trace Phase 1
+
+Establish baseline coverage before new work
+```
+
+### Phase 3: Solutioning (bắt buộc)
+
+**1. Architecture kèm testability review:**
+
+```text
+Architect: architecture
+
+TEA: test-design (system-level)
+
+Focus:
+- Security architecture testability
+- Performance testing strategy
+- Compliance requirement mapping
+```
+
+**2. Hạ tầng kiểm thử:**
+
+```text
+TEA: framework
+
+Requirements:
+- Separate test environments (dev, staging, prod-mirror)
+- Secure test data handling (PHI, PII)
+- Audit logging in tests
+```
+
+**3. CI/CD có tính compliance:**
+
+```text
+TEA: ci
+
+Requirements:
+- Secrets management (Vault, AWS Secrets Manager)
+- Test isolation (no cross-contamination)
+- Artifact retention (compliance audit trail)
+- Access controls (who can run production tests)
+```
+
+### Phase 4: Implementation (bắt buộc)
+
+Cho mỗi epic:
+
+```text
+1. test-design
+2. atdd (optional)
+3. implement
+4. automate
+5. test-review
+6. trace Phase 1
+```
+
+### Release Gate
+
+1. Chạy `nfr-assess` lần cuối
+2. Chạy `test-review` trên toàn bộ suite
+3. Chạy `trace` Phase 2 để ra gate decision
+4. Lưu trữ toàn bộ artifact phục vụ audit
+
+## Yêu cầu đặc thù của enterprise
+
+### Thu thập evidence
+
+Các artifact thường cần:
+
+- Traceability matrix
+- Kết quả chạy test có timestamp
+- NFR assessment report
+- Kết quả security scan
+- Kết quả performance test
+- Gate decision record
+- Chữ ký hoặc phê duyệt từ người có thẩm quyền
+
+**Ví dụ cấu trúc lưu trữ:**
+
+```text
+compliance/
+├── 2026-Q1/
+│ ├── release-1.2.0/
+│ │ ├── traceability-matrix.md
+│ │ ├── test-review.md
+│ │ ├── nfr-assessment.md
+│ │ ├── gate-decision-release-v1.2.0.md
+│ │ ├── test-results/
+│ │ ├── security-scans/
+│ │ └── approvals.pdf
+```
+
+### Approval workflow
+
+Enterprise thường cần phê duyệt nhiều tầng:
+
+```markdown
+## Gate Approvals Required
+
+### Technical Approval
+
+- [ ] QA Lead
+- [ ] Tech Lead
+- [ ] Security Lead
+
+### Business Approval
+
+- [ ] Product Manager
+- [ ] Compliance Officer
+
+### Executive Approval
+
+- [ ] VP Engineering
+- [ ] CTO
+```
+
+### Compliance checklist
+
+**Ví dụ SOC 2:**
+
+- Authentication cho mọi endpoint
+- Authorization đã được test
+- Session management an toàn
+- Audit log đầy đủ
+- Dữ liệu được mã hóa
+
+**Ví dụ HIPAA:**
+
+- PHI được mã hóa khi lưu và khi truyền
+- RBAC đã được test
+- Có audit trail cho truy cập dữ liệu
+- Breach notification workflow đã được kiểm tra
+
+## Mẹo cho enterprise
+
+### Bắt đầu từ security
+
+Security thường là ưu tiên số 1:
+
+1. Liệt kê security requirements
+2. Sinh security test bằng `atdd`
+3. Chạy security suite
+4. Chỉ chuyển bước khi security đạt ngưỡng
+
+### Đặt threshold cao hơn
+
+Ví dụ mục tiêu enterprise:
+
+- Coverage >85%
+- Quality score >85
+- P0 coverage = 100%
+- P1 coverage >95%
+
+### Ghi lại mọi quyết định
+
+Auditor thường cần:
+
+- Vì sao đưa ra quyết định đó
+- Ai phê duyệt
+- Khi nào
+- Dựa trên evidence nào
+
+### Lập ngân sách cho compliance testing
+
+Compliance testing có chi phí thật:
+
+- Pentest
+- Security audit
+- Performance testing tool
+- Compliance consulting
+
+Đây không phải phần "nên có", mà thường là bắt buộc.
+
+### Dùng validator bên ngoài
+
+Đừng tự chứng nhận hoàn toàn:
+
+- Pentest nên có bên thứ ba
+- Security audit nên độc lập
+- Compliance nên do đơn vị chứng nhận thực hiện
+
+Vai trò của TEA là chuẩn bị cho validation bên ngoài, không thay thế nó.
+
+## Tài liệu liên quan
+
+- [How to Run NFR Assessment](/vi-vn/how-to/workflows/run-nfr-assess.md)
+- [How to Run Trace](/vi-vn/how-to/workflows/run-trace.md)
+- [How to Run Test Review](/vi-vn/how-to/workflows/run-test-review.md)
+- [How to Run Test Design](/vi-vn/how-to/workflows/run-test-design.md)
+- [Using TEA with Existing Tests](/vi-vn/how-to/brownfield/use-tea-with-existing-tests.md)
+- [Integrate Playwright Utils](/vi-vn/how-to/customization/integrate-playwright-utils.md)
+
+## Hiểu thêm về khái niệm
+
+- [Engagement Models](/vi-vn/explanation/engagement-models.md)
+- [Risk-Based Testing](/vi-vn/explanation/risk-based-testing.md)
+- [Test Quality Standards](/vi-vn/explanation/test-quality-standards.md)
+- [TEA Overview](/vi-vn/explanation/tea-overview.md)
diff --git a/docs/vi-vn/how-to/brownfield/use-tea-with-existing-tests.md b/docs/vi-vn/how-to/brownfield/use-tea-with-existing-tests.md
new file mode 100644
index 0000000..74a9ce6
--- /dev/null
+++ b/docs/vi-vn/how-to/brownfield/use-tea-with-existing-tests.md
@@ -0,0 +1,361 @@
+---
+title: 'Sử dụng TEA với dự án đã có test (Brownfield)'
+description: Áp dụng workflow TEA cho codebase legacy có bộ test sẵn
+---
+
+# Sử dụng TEA với dự án đã có test (Brownfield)
+
+Hãy dùng TEA trên dự án brownfield để thiết lập baseline coverage, xác định gap và cải thiện chất lượng test mà không cần làm lại toàn bộ từ đầu.
+
+## Khi nào nên dùng
+
+- Codebase đã có sẵn một số test
+- Bộ test legacy cần được cải thiện chất lượng
+- Bạn đang thêm feature vào ứng dụng hiện có
+- Cần hiểu mức coverage hiện tại
+- Muốn giảm nguy cơ regression khi tiếp tục mở rộng hệ thống
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method
+- Agent TEA đã sẵn sàng
+- Codebase hiện có test, dù chưa đầy đủ hoặc chất lượng chưa cao
+- Test có thể chạy được, ít nhất là chạy để quan sát hiện trạng
+
+**Lưu ý:** Nếu codebase hầu như chưa được tài liệu hóa, hãy chạy `document-project` trước để có baseline documentation.
+
+## Chiến lược Brownfield
+
+### Phase 1: Thiết lập baseline
+
+Trước khi thay đổi bất cứ thứ gì, hãy hiểu rõ mình đang có gì.
+
+#### Bước 1: Dùng `trace` để chốt baseline coverage
+
+Chạy `trace` Phase 1:
+
+```text
+trace
+```
+
+**Chọn:** `Phase 1 (Requirements Traceability)`
+
+**Cung cấp:**
+
+- Requirements doc hiện có như PRD, story, feature spec
+- Vị trí test, ví dụ `tests/`
+- Focus area nếu codebase lớn
+
+**Đầu ra:** `traceability-matrix.md`, cho bạn biết:
+
+- Requirement nào đã có test
+- Requirement nào chưa có coverage
+- Mức FULL / PARTIAL / NONE
+- Gap nào cần ưu tiên
+
+**Ví dụ baseline:**
+
+```markdown
+# Baseline Coverage (Before Improvements)
+
+**Total Requirements:** 50
+**Full Coverage:** 15 (30%)
+**Partial Coverage:** 20 (40%)
+**No Coverage:** 15 (30%)
+
+**By Priority:**
+
+- P0: 50% coverage (5/10) ❌ Critical gap
+- P1: 40% coverage (8/20) ⚠️ Needs improvement
+- P2: 20% coverage (2/10) ✅ Acceptable
+```
+
+Đây sẽ là mốc để bạn đo mức cải thiện sau này.
+
+#### Bước 2: Audit chất lượng với `test-review`
+
+Chạy:
+
+```text
+test-review tests/
+```
+
+**Đầu ra:** `test-review.md` với điểm chất lượng và danh sách issue.
+
+**Các vấn đề brownfield thường gặp:**
+
+- Hard wait ở khắp nơi
+- CSS selector mong manh
+- Test phụ thuộc thứ tự chạy
+- `try/catch` hoặc `if/else` để điều khiển flow
+- Test không dọn dữ liệu sau khi chạy
+
+**Ví dụ baseline quality:**
+
+```markdown
+# Quality Score: 55/100
+
+**Critical Issues:** 12
+
+- 8 hard waits
+- 4 conditional flow control
+```
+
+### Phase 2: Ưu tiên cải tiến
+
+Đừng cố sửa mọi thứ cùng lúc.
+
+#### Bắt đầu từ critical path
+
+**Ưu tiên 1: P0 requirement**
+
+```text
+Goal: Get P0 coverage to 100%
+
+Actions:
+1. Identify P0 requirements with no tests
+2. Run `automate` to generate tests for missing P0 scenarios
+3. Fix critical quality issues in P0 tests
+```
+
+**Ưu tiên 2: Sửa flaky test**
+
+```text
+Goal: Eliminate flakiness
+
+Actions:
+1. Identify tests with hard waits
+2. Replace with network-first patterns
+3. Run burn-in loops to verify stability
+```
+
+**Ví dụ hiện đại hóa:**
+
+**Trước:**
+
+```typescript
+test('checkout completes', async ({ page }) => {
+ await page.click('button[name=\"checkout\"]');
+ await page.waitForTimeout(5000);
+ await expect(page.locator('.confirmation')).toBeVisible();
+});
+```
+
+**Sau (network-first):**
+
+```typescript
+test('checkout completes', async ({ page }) => {
+ const checkoutPromise = page.waitForResponse((resp) => resp.url().includes('/api/checkout') && resp.ok());
+ await page.click('button[name=\"checkout\"]');
+ await checkoutPromise;
+ await expect(page.locator('.confirmation')).toBeVisible();
+});
+```
+
+**Sau (với Playwright Utils):**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+import { expect } from '@playwright/test';
+
+test('checkout completes', async ({ page, interceptNetworkCall }) => {
+ const checkoutCall = interceptNetworkCall({
+ method: 'POST',
+ url: '**/api/checkout',
+ });
+
+ await page.click('button[name=\"checkout\"]');
+ const { status, responseJson: order } = await checkoutCall;
+
+ expect(status).toBe(200);
+ expect(order.status).toBe('confirmed');
+ await expect(page.locator('.confirmation')).toBeVisible();
+});
+```
+
+**Ưu tiên 3: P1 requirement**
+
+- Sinh test cho gap P1 có rủi ro cao
+- Nâng chất lượng test từng bước
+
+#### Tạo roadmap cải tiến
+
+```markdown
+# Test Improvement Roadmap
+
+## Week 1: Critical Path (P0)
+
+- [ ] Add 5 missing P0 tests
+- [ ] Fix 8 hard waits
+- [ ] Verify P0 coverage = 100%
+
+## Week 2: Flakiness
+
+- [ ] Replace all hard waits with network-first
+- [ ] Fix conditional flow control
+- [ ] Run burn-in loops
+```
+
+### Phase 3: Cải tiến tăng dần
+
+#### Với feature mới trong codebase cũ
+
+Bạn vẫn nên dùng workflow TEA đầy đủ:
+
+```text
+1. test-design
+2. atdd
+3. implement
+4. automate
+5. test-review
+```
+
+Điều này giúp code mới có chất lượng tốt từ ngày đầu, đồng thời kéo dần toàn bộ suite lên chuẩn cao hơn.
+
+#### Với bug fix
+
+Hãy thêm regression test:
+
+```text
+1. Reproduce bug with failing test
+2. Fix bug
+3. Verify test passes
+4. Run test-review
+5. Add to regression suite
+```
+
+#### Với refactoring
+
+Trước và sau refactor, dùng `trace` để đảm bảo coverage không bị giảm.
+
+### Phase 4: Cải tiến liên tục
+
+Hãy theo dõi tiến bộ theo quý:
+
+```text
+Q1: Coverage 30%, Quality 55, Flakiness 15%
+Q2: Coverage 50%, Quality 65, Flakiness 5%
+Q3: Coverage 70%, Quality 75, Flakiness 1%
+Q4: Coverage 85%, Quality 85, Flakiness <0.5%
+```
+
+## Mẹo đặc thù cho Brownfield
+
+### Đừng viết lại mọi thứ
+
+Thay vì xóa toàn bộ suite cũ:
+
+1. Giữ lại test đang còn giá trị
+2. Sửa critical issue từng bước
+3. Bổ sung gap quan trọng
+4. Cải tiến dần theo thời gian
+
+### Dùng regression hotspot
+
+Xác định khu vực hay lỗi nhất dựa trên:
+
+- Bug report
+- Khiếu nại từ người dùng
+- Code complexity
+- Khu vực thay đổi thường xuyên
+
+Ưu tiên thêm test regression ở đây trước.
+
+### Quarantine flaky test
+
+Tạm `skip` test quá flaky, nhưng phải theo dõi:
+
+```markdown
+# Quarantined Tests
+
+| Test | Reason | Owner | Target Fix Date |
+| ------------------- | -------------------------- | ------- | --------------- |
+| checkout.spec.ts:45 | Hard wait causes flakiness | QA Team | 2026-01-20 |
+```
+
+### Nâng cấp theo từng thư mục
+
+Ví dụ:
+
+- Tuần 1: `tests/auth/`
+- Tuần 2: `tests/api/`
+- Tuần 3: `tests/e2e/`
+
+Như vậy bạn sẽ có tiến độ nhìn thấy được và rủi ro thấp hơn.
+
+## Khó khăn thường gặp
+
+### “Không ai biết test đang bao phủ gì”
+
+Giải pháp:
+
+1. Chạy `trace`
+2. Review traceability matrix
+3. Ghi lại baseline
+4. Dùng đó làm cơ sở cải tiến
+
+### “Test quá giòn, không dám đụng”
+
+Giải pháp:
+
+1. Chạy test để ghi nhận baseline
+2. Sửa một vấn đề nhỏ
+3. Chạy lại
+4. Nếu ổn, tiếp tục
+
+### “Không ai biết cách chạy test”
+
+Giải pháp:
+
+Tạo `tests/README.md` nêu:
+
+- Cách cài dependency
+- Cách chạy test
+- Ý nghĩa các thư mục test
+- Vấn đề thường gặp
+
+### “Suite chạy quá lâu”
+
+Giải pháp:
+
+1. Sharding / parallelization
+2. Selective testing
+3. Chỉ chạy full suite theo lịch
+4. Tối ưu test chậm
+
+## Workflow TEA khuyến nghị cho Brownfield
+
+```text
+1. document-project (nếu thiếu tài liệu)
+2. trace Phase 1
+3. test-review
+4. test-design (system-level)
+5. framework / ci (nếu cần nâng hạ tầng)
+6. per epic: test-design -> automate -> test-review -> trace
+7. release gate: nfr-assess + trace Phase 2
+```
+
+## Tài liệu liên quan
+
+- [How to Run Trace](/vi-vn/how-to/workflows/run-trace.md)
+- [How to Run Test Review](/vi-vn/how-to/workflows/run-test-review.md)
+- [How to Run Automate](/vi-vn/how-to/workflows/run-automate.md)
+- [How to Run Test Design](/vi-vn/how-to/workflows/run-test-design.md)
+- [Integrate Playwright Utils](/vi-vn/how-to/customization/integrate-playwright-utils.md)
+
+## Hiểu thêm về khái niệm
+
+- [Engagement Models](/vi-vn/explanation/engagement-models.md)
+- [Test Quality Standards](/vi-vn/explanation/test-quality-standards.md)
+- [Network-First Patterns](/vi-vn/explanation/network-first-patterns.md)
+- [Risk-Based Testing](/vi-vn/explanation/risk-based-testing.md)
+
+## Tham chiếu
+
+- [TEA Command Reference](/vi-vn/reference/commands.md)
+- [TEA Configuration](/vi-vn/reference/configuration.md)
+- [Knowledge Base Index](/vi-vn/reference/knowledge-base.md)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/customization/configure-browser-automation.md b/docs/vi-vn/how-to/customization/configure-browser-automation.md
new file mode 100644
index 0000000..2adc877
--- /dev/null
+++ b/docs/vi-vn/how-to/customization/configure-browser-automation.md
@@ -0,0 +1,216 @@
+---
+title: 'Cấu hình Browser Automation'
+description: Thiết lập Playwright CLI và MCP để dùng browser automation trong các workflow của TEA
+---
+
+# Cấu hình Browser Automation
+
+TEA có thể tương tác với browser thật trong lúc sinh test để xác minh selector, khám phá UI, thu thập bằng chứng và debug lỗi. Có hai công cụ bổ sung cho nhau:
+
+**CLI và MCP là hai công cụ bổ trợ, không phải đối thủ.** Chế độ `auto` dùng mỗi công cụ ở nơi nó phù hợp nhất: CLI cho snapshot stateless tiết kiệm token, MCP cho automation giàu trạng thái.
+
+## Bốn chế độ
+
+Browser automation của TEA được điều khiển bằng `tea_browser_automation` trong `_bmad/tea/config.yaml`:
+
+```yaml
+tea_browser_automation: 'auto' # auto | cli | mcp | none
+```
+
+| Chế độ | Hành vi |
+| ------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `auto` | TEA tự chọn công cụ phù hợp cho từng hành động. Có fallback an toàn nếu chỉ có một công cụ được cài. **(Khuyến nghị)** |
+| `cli` | Chỉ dùng CLI, bỏ qua MCP kể cả khi đã cấu hình. |
+| `mcp` | Chỉ dùng MCP, bỏ qua CLI kể cả khi đã cài. Tương đương hành vi cũ của `tea_use_mcp_enhancements: true`. |
+| `none` | Không tương tác browser, chỉ sinh từ docs và code analysis. |
+
+## Điều kiện tiên quyết
+
+### Với CLI (`cli` hoặc `auto`)
+
+```bash
+npm install -g @playwright/cli@latest
+playwright-cli install --skills
+```
+
+Lệnh cài npm toàn cục chỉ cần chạy một lần. Phần `playwright-cli install --skills` nên chạy ở root dự án để đăng ký skill vào thư mục skill của công cụ hiện tại.
+
+### Với MCP (`mcp` hoặc `auto`)
+
+Thêm MCP server vào file cấu hình của công cụ bạn đang dùng:
+
+```json
+{
+ "mcpServers": {
+ "playwright": {
+ "type": "stdio",
+ "command": "npx",
+ "args": ["-y", "@playwright/mcp@latest"]
+ },
+ "playwright-test": {
+ "type": "stdio",
+ "command": "npx",
+ "args": ["playwright", "run-test-mcp-server"]
+ },
+ "smartbear": {
+ "type": "stdio",
+ "command": "npx",
+ "args": ["-y", "@smartbear/mcp@latest"],
+ "env": {
+ "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+ "PACT_BROKER_TOKEN": ""
+ }
+ }
+ }
+}
+```
+
+`smartbear` là tùy chọn, chỉ cần khi bạn dùng tích hợp Pact MCP.
+
+### Đặt cấu hình ở đâu
+
+| Công cụ | File cấu hình | Định dạng |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code | `~/.claude.json` | JSON (`mcpServers`) |
+| Codex | `~/.codex/config.toml` | TOML (`[mcp_servers]`) |
+| Gemini CLI | `~/.gemini/settings.json` | JSON (`mcpServers`) |
+| Cursor | `~/.cursor/mcp.json` | JSON (`mcpServers`) |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`) |
+| VS Code (Copilot) | `.vscode/mcp.json` | JSON (`servers`) |
+
+> **Mẹo với Claude Code:** ưu tiên dùng `claude mcp add` thay vì sửa JSON tay để tránh sai định dạng.
+
+### CLI shortcut
+
+```bash
+# Claude Code
+claude mcp add -s user --transport stdio playwright -- npx -y @playwright/mcp@latest
+claude mcp add -s user --transport stdio playwright-test -- npx playwright run-test-mcp-server
+
+# Codex
+codex mcp add playwright -- npx -y @playwright/mcp@latest
+codex mcp add playwright-test -- npx playwright run-test-mcp-server
+```
+
+### Định dạng TOML cho Codex
+
+```toml
+[mcp_servers.playwright]
+command = "npx"
+args = ["-y", "@playwright/mcp@latest"]
+
+[mcp_servers.playwright-test]
+command = "npx"
+args = ["playwright", "run-test-mcp-server"]
+```
+
+Lưu ý khóa là `mcp_servers`, không phải `mcpServers`.
+
+## Cách `auto` mode hoạt động
+
+Khi `tea_browser_automation: "auto"`, TEA chọn công cụ theo ngữ cảnh:
+
+### Ưu tiên 1: User override
+
+Nếu bạn nói rõ “dùng CLI” hoặc “dùng MCP”, TEA sẽ tôn trọng.
+
+### Ưu tiên 2: Auto heuristic
+
+**CLI phù hợp hơn cho tác vụ stateless, nhanh:**
+
+- Mở trang, chụp snapshot, liệt kê element
+- Chụp selector hoặc cấu trúc trang
+- Xác minh locator có tồn tại hay không
+- Chụp screenshot/trace làm bằng chứng
+
+**MCP phù hợp hơn cho tác vụ stateful, nhiều bước:**
+
+- Luồng dài cần giữ trạng thái
+- Multi-tab, upload file, wizard nhiều bước
+- Tương tác phức tạp như drag/drop
+- Self-healing khi cần đọc DOM sâu hơn
+
+### Ưu tiên 3: Fallback
+
+- Nếu CLI không có -> fallback sang MCP
+- Nếu MCP không có -> fallback sang CLI
+- Nếu cả hai đều không có -> quay về `none`
+
+## Workflow nào hưởng lợi
+
+| Workflow | Công cụ thường dùng ở `auto` | Use case |
+| ------------- | ---------------------------- | ---------------------------------------------------- |
+| `test-design` | CLI | Khám phá trang, snapshot, discovery |
+| `atdd` | CLI + MCP | Capture cơ bản bằng CLI, tương tác phức tạp bằng MCP |
+| `automate` | CLI + MCP | Verify selector bằng CLI, healing bằng MCP |
+| `test-review` | CLI | Thu thập trace, screenshot, network |
+| `nfr-assess` | CLI | Theo dõi timing và network |
+
+## Override theo từng yêu cầu
+
+Ngay cả khi đang dùng `auto`, bạn vẫn có thể chỉ định:
+
+```text
+Use the CLI to snapshot the login page
+Open MCP browser and walk through the checkout wizard
+```
+
+TEA sẽ làm theo yêu cầu tường minh đó.
+
+## Chuyển từ `tea_use_mcp_enhancements`
+
+| Thiết lập cũ | Thiết lập mới tương đương |
+| --------------------------------- | -------------------------------- |
+| `tea_use_mcp_enhancements: true` | `tea_browser_automation: "auto"` |
+| `tea_use_mcp_enhancements: false` | `tea_browser_automation: "none"` |
+
+Installer của BMAD sẽ tự migrate cấu hình cũ nếu cần.
+
+## Khắc phục sự cố
+
+### CLI không hoạt động
+
+```bash
+playwright-cli --version
+npm install -g @playwright/cli@latest
+playwright-cli install --skills
+```
+
+### MCP không hoạt động
+
+1. Kiểm tra MCP server đã được khai báo trong IDE chưa
+2. Khởi động lại IDE sau khi sửa config
+3. Kiểm tra:
+
+```bash
+npx @playwright/mcp@latest --version
+```
+
+### Auto mode không chọn đúng công cụ như mong muốn
+
+Auto mode thường log lý do:
+
+- `Using CLI for snapshot (stateless discovery)`
+- `Using MCP for multi-step recording (stateful flow)`
+
+Hãy xem output của workflow để biết vì sao nó chọn công cụ đó.
+
+### Dọn session bị treo
+
+Nếu có browser process bị treo:
+
+```bash
+playwright-cli list
+playwright-cli -s=tea-explore close
+playwright-cli close-all
+```
+
+## Tài liệu liên quan
+
+- [TEA Overview -- Browser Automation](/vi-vn/explanation/tea-overview.md)
+- [Integrate Playwright Utils](/vi-vn/how-to/customization/integrate-playwright-utils.md)
+- [TEA Configuration Reference](/vi-vn/reference/configuration.md)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/customization/extend-tea-with-custom-workflows.md b/docs/vi-vn/how-to/customization/extend-tea-with-custom-workflows.md
new file mode 100644
index 0000000..861244d
--- /dev/null
+++ b/docs/vi-vn/how-to/customization/extend-tea-with-custom-workflows.md
@@ -0,0 +1,87 @@
+---
+title: 'Mở rộng TEA bằng workflow tùy chỉnh'
+description: Thêm workflow riêng vào bmad-tea mà không phải vá trực tiếp TEA core
+---
+
+# Mở rộng TEA bằng workflow tùy chỉnh
+
+TEA hiện là một module độc lập. Điều đó có nghĩa là custom workflow vẫn được hỗ trợ, nhưng chúng sẽ **không tự động được gộp vào TEA core** sau mỗi lần cập nhật. Cách an toàn là mở rộng qua cơ chế customization thay vì patch trực tiếp core.
+
+## Mô hình được hỗ trợ
+
+Bạn nên dùng một trong các cách sau:
+
+1. Đóng gói workflow thành custom content hoặc custom module
+2. Thêm menu entry vào `bmad-tea` thông qua BMAD agent customization
+3. Cài lại hoặc quick-update BMAD để workflow và menu entry được đăng ký lại
+
+Cách này giúp extension của bạn vẫn tương thích với cập nhật từ upstream.
+
+## Cách làm khuyến nghị
+
+### 1. Tạo workflow như custom content
+
+Dùng BMad Builder hoặc cấu trúc custom module của riêng bạn để tạo workflow sống **ngoài TEA core**.
+
+- BMAD hỗ trợ custom module trong lúc cài đặt hoặc update
+- BMad Builder là con đường khuyến nghị để tạo agent và workflow có thể tái sử dụng
+
+Xem thêm:
+
+- [How to Customize BMad](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/how-to/customize-bmad.md)
+- [BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)
+
+### 2. Gắn workflow vào `bmad-tea`
+
+Sau khi TEA được cài, dùng file agent customization sinh ra cho `bmad-tea` trong `_bmad/_config/agents/` rồi thêm menu item:
+
+```yaml
+menu:
+ - trigger: my-custom-workflow
+ workflow: 'my-custom/workflows/my-custom-workflow.yaml'
+ description: My custom TEA extension workflow
+```
+
+Cách này giữ nguyên trải nghiệm menu/chat của `bmad-tea`, nhưng vẫn route sang workflow tùy chỉnh của bạn.
+
+### 3. Cài lại hoặc quick-update BMAD
+
+Chạy:
+
+```bash
+npx bmad-method install
+```
+
+Sau đó chọn đường cập nhật bình thường để BMAD áp lại customization và làm mới việc đăng ký workflow.
+
+## Điều không nên làm
+
+- Không patch trực tiếp file TEA core nếu workflow chỉ phục vụ một dự án cụ thể
+- Không dựa vào hành vi cũ kiểu embedded-TEA, nơi workflow local tự xuất hiện như gắn sẵn
+- Không để toàn bộ logic custom workflow chỉ nằm trong chat instructions; hãy đặt nó vào workflow hoặc module thật
+
+## Khi nào nên chọn cách nào
+
+- **Workflow theo dự án cụ thể:** thêm custom content rồi gắn vào `bmad-tea`
+- **Workflow nội bộ có thể tái sử dụng:** đóng gói thành custom module
+- **Workflow công khai có thể tái dùng rộng hơn:** cân nhắc publish như một BMAD module độc lập
+
+## Gợi ý cho QC
+
+Các khu vực đáng cân nhắc mở rộng:
+
+- compliance testing
+- domain data validation
+- environment readiness
+- specialized regression audit
+- release evidence packaging
+
+## Tài liệu liên quan
+
+- [TEA Command Reference](/docs/vi-vn/reference/commands.md)
+- [TEA Configuration Reference](/docs/vi-vn/reference/configuration.md)
+- [How to Customize BMad](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/how-to/customize-bmad.md)
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/customization/integrate-playwright-utils.md b/docs/vi-vn/how-to/customization/integrate-playwright-utils.md
new file mode 100644
index 0000000..46da4ea
--- /dev/null
+++ b/docs/vi-vn/how-to/customization/integrate-playwright-utils.md
@@ -0,0 +1,454 @@
+---
+title: 'Tích hợp Playwright Utils với TEA'
+description: Bổ sung fixture và utility sẵn sàng cho production vào bộ test do TEA sinh ra
+---
+
+# Tích hợp Playwright Utils với TEA
+
+Tích hợp `@seontechnologies/playwright-utils` với TEA để có fixture, utility và pattern chất lượng production trong test suite.
+
+## Playwright Utils là gì?
+
+Đây là thư viện utility sẵn sàng cho production, cung cấp:
+
+- Typed API request helper
+- Quản lý authentication session
+- Record và replay network (HAR)
+- Intercept network request
+- Async polling (`recurse`)
+- Structured logging
+- Xác thực file CSV, PDF, XLSX, ZIP
+- Burn-in testing utility
+- Network error monitoring
+
+**Repository:**
+**npm package:** `@seontechnologies/playwright-utils`
+
+## Khi nào nên dùng
+
+- Bạn muốn fixture production-ready thay vì tự dựng từ đầu
+- Đội của bạn hưởng lợi từ pattern chuẩn hóa
+- Bạn cần utility như API testing, auth handling, network mocking
+- Bạn muốn TEA sinh test theo đúng utility này
+- Bạn đang xây reusable test infrastructure
+
+**Không nên dùng khi:**
+
+- Bạn chỉ đang mới học testing
+- Đội đã có fixture library riêng
+- Bạn không cần các utility này
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method
+- Agent TEA đã sẵn sàng
+- Đã thiết lập test framework bằng Playwright
+- Node.js v18 trở lên
+
+**Lưu ý:** Playwright Utils chỉ dành cho Playwright, không dùng cho Cypress.
+
+## Cài đặt
+
+### Bước 1: Cài package
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+### Bước 2: Bật trong cấu hình TEA
+
+Sửa `_bmad/tea/config.yaml`:
+
+```yaml
+tea_use_playwright_utils: true
+```
+
+### Bước 3: Kiểm tra
+
+```bash
+npm list @seontechnologies/playwright-utils
+grep tea_use_playwright_utils _bmad/tea/config.yaml
+```
+
+Kết quả nên cho thấy package đã được cài và biến cấu hình đang là `true`.
+
+## Khi bật lên thì thay đổi gì?
+
+### Workflow `framework`
+
+**Vanilla Playwright:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('api test', async ({ request }) => {
+ const response = await request.get('/api/users');
+ const users = await response.json();
+ expect(response.status()).toBe(200);
+});
+```
+
+**Với Playwright Utils (combined fixtures):**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+import { expect } from '@playwright/test';
+
+test('api test', async ({ apiRequest, authToken, log }) => {
+ const { status, body } = await apiRequest({
+ method: 'GET',
+ path: '/api/users',
+ headers: { Authorization: `Bearer ${authToken}` },
+ });
+
+ log.info('Fetched users', body);
+ expect(status).toBe(200);
+});
+```
+
+**Với selective merge:**
+
+```typescript
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+export const test = mergeTests(apiRequestFixture, logFixture);
+export { expect } from '@playwright/test';
+```
+
+### Workflow `atdd` và `automate`
+
+**Không dùng Playwright Utils:**
+
+```typescript
+test('should fetch profile', async ({ request }) => {
+ const response = await request.get('/api/profile');
+ const profile = await response.json();
+});
+```
+
+**Có dùng Playwright Utils:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch profile', async ({ apiRequest }) => {
+ const { status, body } = await apiRequest({
+ method: 'GET',
+ path: '/api/profile',
+ }).validateSchema(ProfileSchema);
+
+ expect(status).toBe(200);
+});
+```
+
+### Workflow `test-review`
+
+- Nếu không bật utility này, TEA review theo Playwright pattern chung
+- Nếu bật, TEA review theo best practice riêng của Playwright Utils như:
+ - fixture composition
+ - utility usage
+ - network-first patterns
+ - structured logging
+
+### Workflow `ci`
+
+Khi bật, TEA có thể sinh CI tốt hơn với:
+
+- burn-in utility
+- selective testing
+- test prioritization theo thay đổi file
+
+## Các utility hiện có
+
+### `api-request`
+
+HTTP client có type và hỗ trợ schema validation.
+
+**Ưu điểm so với Playwright mặc định:**
+
+- Tự parse JSON
+- Trả về `{ status, body }`
+- Retry tự động cho lỗi 5xx
+- Có `.validateSchema()`
+
+**Ví dụ:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { expect } from '@playwright/test';
+import { z } from 'zod';
+
+const UserSchema = z.object({
+ id: z.string(),
+ name: z.string(),
+ email: z.string().email(),
+});
+
+test('should create user', async ({ apiRequest }) => {
+ const { status, body } = await apiRequest({
+ method: 'POST',
+ path: '/api/users',
+ body: { name: 'Test User', email: 'test@example.com' },
+ }).validateSchema(UserSchema);
+
+ expect(status).toBe(201);
+ expect(body.id).toBeDefined();
+});
+```
+
+### `auth-session`
+
+Quản lý session xác thực với token persistence.
+
+**Ưu điểm:**
+
+- Xác thực một lần, dùng lại nhiều test
+- Token được lưu xuống đĩa
+- Hỗ trợ multi-user
+- Tự renew token nếu hết hạn
+
+**Ví dụ:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { expect } from '@playwright/test';
+
+test('should access protected route', async ({ page, authToken }) => {
+ await page.goto('/dashboard');
+ await expect(page).toHaveURL('/dashboard');
+});
+```
+
+### `network-recorder`
+
+Ghi và phát lại lưu lượng mạng bằng HAR.
+
+**Ví dụ chuyển chế độ:**
+
+```bash
+PW_NET_MODE=record npx playwright test
+PW_NET_MODE=playback npx playwright test
+```
+
+**Lợi ích:**
+
+- Offline testing
+- Response deterministic
+- Chạy nhanh hơn vì không phụ thuộc backend thật
+
+### `intercept-network-call`
+
+Spy hoặc stub request mạng và tự parse JSON.
+
+**Ví dụ:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should handle API errors', async ({ page, interceptNetworkCall }) => {
+ const profileCall = interceptNetworkCall({
+ method: 'GET',
+ url: '**/api/profile',
+ fulfillResponse: {
+ status: 500,
+ body: { error: 'Server error' },
+ },
+ });
+
+ await page.goto('/profile');
+ const { status, responseJson } = await profileCall;
+ expect(status).toBe(500);
+ expect(responseJson.error).toBe('Server error');
+});
+```
+
+### `recurse`
+
+Polling thông minh cho eventual consistency.
+
+**Ví dụ:**
+
+```typescript
+const completed = await recurse(
+ () => apiRequest({ method: 'GET', path: `/api/jobs/${job.id}` }),
+ (result) => result.body.status === 'completed',
+ { timeout: 30000, interval: 2000, log: 'Waiting for job to complete' },
+);
+```
+
+### `log`
+
+Structured logging tích hợp với Playwright report.
+
+**Ví dụ:**
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+await log.info('Starting login test');
+await log.step('Navigated to login page');
+await log.success('Login completed');
+```
+
+### `file-utils`
+
+Đọc và validate CSV, PDF, XLSX, ZIP.
+
+**Ví dụ CSV:**
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+
+const downloadPath = await handleDownload({
+ page,
+ downloadDir: DOWNLOAD_DIR,
+ trigger: () => page.click('button:has-text("Export")'),
+});
+
+const csvResult = await readCSV({ filePath: downloadPath });
+```
+
+### `burn-in`
+
+Chọn test thông minh cho CI dựa trên git diff.
+
+**Ví dụ script:**
+
+```typescript
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+await runBurnIn({
+ configPath: 'playwright.burn-in.config.ts',
+ baseBranch: 'main',
+});
+```
+
+### `network-error-monitor`
+
+Tự động phát hiện HTTP 4xx/5xx trong lúc test.
+
+**Ví dụ:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+test('should not have API errors', async ({ page }) => {
+ await page.goto('/dashboard');
+ await page.click('button');
+});
+```
+
+Bạn có thể opt-out bằng annotation khi đang cố tình test luồng lỗi.
+
+## Fixture composition
+
+### Cách 1: Dùng combined fixtures của package
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+import { log } from '@seontechnologies/playwright-utils';
+import { expect } from '@playwright/test';
+```
+
+### Cách 2: Tạo merged fixture riêng
+
+**File 1: `support/merged-fixtures.ts`**
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequest } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as interceptNetworkCall } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as networkErrorMonitor } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+import { log } from '@seontechnologies/playwright-utils';
+
+export const test = mergeTests(base, apiRequest, interceptNetworkCall, networkErrorMonitor);
+export const expect = base.expect;
+export { log };
+```
+
+**File 2: `tests/api/users.spec.ts`**
+
+```typescript
+import { test, expect, log } from '../support/merged-fixtures';
+```
+
+**So sánh:**
+
+- Cách 1: nhanh, có sẵn mọi utility
+- Cách 2: chọn đúng utility cần dùng, dễ kiểm soát hơn
+
+## Khắc phục sự cố
+
+### Lỗi import
+
+```bash
+npm list @seontechnologies/playwright-utils
+npm install -D @seontechnologies/playwright-utils
+```
+
+### TEA không dùng utility này
+
+Kiểm tra:
+
+```bash
+grep tea_use_playwright_utils _bmad/tea/config.yaml
+```
+
+Nếu vừa đổi config, hãy mở chat mới rồi chạy lại workflow.
+
+### Type error với `apiRequest`
+
+Nguyên nhân thường là chưa dùng schema validation.
+
+**Cách xử lý:**
+
+```typescript
+import { z } from 'zod';
+
+const ProfileSchema = z.object({
+ id: z.string(),
+ name: z.string(),
+ email: z.string().email(),
+});
+
+const { status, body } = await apiRequest({
+ method: 'GET',
+ path: '/api/profile',
+}).validateSchema(ProfileSchema);
+```
+
+## Tài liệu liên quan
+
+### Getting Started
+
+- [TEA Lite Quickstart Tutorial](/vi-vn/tutorials/tea-lite-quickstart.md)
+- [How to Set Up Test Framework](/vi-vn/how-to/workflows/setup-test-framework.md)
+
+### Workflow Guides
+
+- [How to Run ATDD](/vi-vn/how-to/workflows/run-atdd.md)
+- [How to Run Automate](/vi-vn/how-to/workflows/run-automate.md)
+- [How to Run Test Review](/vi-vn/how-to/workflows/run-test-review.md)
+
+### Other Customization
+
+- [Configure Browser Automation](/vi-vn/how-to/customization/configure-browser-automation.md)
+
+## Hiểu thêm về khái niệm
+
+- [Testing as Engineering](/vi-vn/explanation/testing-as-engineering.md)
+- [Fixture Architecture](/vi-vn/explanation/fixture-architecture.md)
+- [Network-First Patterns](/vi-vn/explanation/network-first-patterns.md)
+- [Test Quality Standards](/vi-vn/explanation/test-quality-standards.md)
+
+## Tham chiếu
+
+- [TEA Configuration](/vi-vn/reference/configuration.md)
+- [Knowledge Base Index](/vi-vn/reference/knowledge-base.md)
+- [Official PW-Utils Docs](https://seontechnologies.github.io/playwright-utils/)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/workflows/run-atdd.md b/docs/vi-vn/how-to/workflows/run-atdd.md
new file mode 100644
index 0000000..621de27
--- /dev/null
+++ b/docs/vi-vn/how-to/workflows/run-atdd.md
@@ -0,0 +1,429 @@
+---
+title: 'Cách chạy ATDD với TEA'
+description: Sinh acceptance test scaffold ở pha đỏ trước khi implementation bằng workflow ATDD của TEA
+---
+
+# Cách chạy ATDD với TEA
+
+Dùng workflow `atdd` của TEA để sinh scaffold acceptance test ở **pha đỏ** trước khi implementation bắt đầu. Hiện tại TEA sinh các scaffold này dưới dạng `test.skip()` để bạn có thể review, gắn vào story và kích hoạt dần theo từng task trong lúc implement.
+
+## Khi nào nên dùng
+
+- Bạn sắp implement một feature **mới**
+- Muốn làm theo luồng TDD: red → green → refactor
+- Muốn để test dẫn dắt việc implement
+- Đang thực hành acceptance test-driven development
+
+**Không nên dùng khi:**
+
+- Feature đã tồn tại, lúc đó nên dùng `automate`
+- Bạn cần bộ test pass ngay
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method
+- Agent TEA có sẵn
+- Test framework đã được thiết lập xong, nếu chưa thì chạy `framework`
+- Story hoặc feature đã được định nghĩa với acceptance criteria rõ ràng
+
+**Lưu ý:** Tài liệu này dùng ví dụ với Playwright. Nếu dùng Cypress thì cú pháp sẽ khác.
+
+## Các bước thực hiện
+
+### 1. Nạp agent TEA
+
+Mở chat mới và chạy:
+
+```text
+tea
+```
+
+### 2. Chạy workflow ATDD
+
+```text
+atdd
+```
+
+### 3. Cung cấp ngữ cảnh
+
+TEA sẽ hỏi:
+
+**Chi tiết story/feature:**
+
+```text
+We're adding a user profile page where users can:
+- View their profile information
+- Edit their name and email
+- Upload a profile picture
+- Save changes with validation
+```
+
+**Acceptance criteria:**
+
+```text
+Given I'm logged in
+When I navigate to /profile
+Then I see my current name and email
+
+Given I'm on the profile page
+When I click "Edit Profile"
+Then I can modify my name and email
+
+Given I've edited my profile
+When I click "Save"
+Then my changes are persisted
+And I see a success message
+
+Given I upload an invalid file type
+When I try to save
+Then I see an error message
+And changes are not saved
+```
+
+**Tài liệu tham chiếu** nếu có:
+
+- Story file
+- PRD hoặc tech spec
+- Test design nếu bạn đã chạy `test-design` trước đó
+
+### 4. Chỉ định test level
+
+TEA sẽ hỏi bạn muốn sinh scaffold ở mức nào:
+
+- E2E tests
+- API tests
+- Component tests
+- Kết hợp nhiều mức
+
+### Component testing theo framework
+
+| Framework | Tool component testing |
+| -------------- | --------------------------------------------- |
+| **Cypress** | Cypress Component Testing (`*.cy.tsx`) |
+| **Playwright** | Vitest + React Testing Library (`*.test.tsx`) |
+
+**Ví dụ câu trả lời:**
+
+```text
+Generate:
+- API tests for profile CRUD operations
+- E2E tests for the complete profile editing flow
+- Component tests for ProfileForm validation
+- Focus on P0 and P1 scenarios
+```
+
+### 5. Review test được sinh ra
+
+TEA sẽ sinh **red-phase scaffold** ở thư mục phù hợp.
+
+#### API tests (`tests/api/profile.spec.ts`)
+
+**Vanilla Playwright:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Profile API', () => {
+ test.skip('should fetch user profile', async ({ request }) => {
+ const response = await request.get('/api/profile');
+
+ expect(response.status()).toBe(200);
+ const profile = await response.json();
+ expect(profile).toHaveProperty('name');
+ expect(profile).toHaveProperty('email');
+ expect(profile).toHaveProperty('avatarUrl');
+ });
+
+ test.skip('should update user profile', async ({ request }) => {
+ const response = await request.patch('/api/profile', {
+ data: {
+ name: 'Updated Name',
+ email: 'updated@example.com',
+ },
+ });
+
+ expect(response.status()).toBe(200);
+ const updated = await response.json();
+ expect(updated.name).toBe('Updated Name');
+ expect(updated.email).toBe('updated@example.com');
+ });
+
+ test.skip('should validate email format', async ({ request }) => {
+ const response = await request.patch('/api/profile', {
+ data: {
+ email: 'invalid-email',
+ },
+ });
+
+ expect(response.status()).toBe(400);
+ const error = await response.json();
+ expect(error.message).toContain('Invalid email format');
+ });
+});
+```
+
+**Với Playwright Utils:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { expect } from '@playwright/test';
+import { z } from 'zod';
+
+const ProfileSchema = z.object({
+ name: z.string(),
+ email: z.string().email(),
+ avatarUrl: z.string().url(),
+});
+
+test.describe('Profile API', () => {
+ test.skip('should fetch user profile', async ({ apiRequest }) => {
+ const { status, body } = await apiRequest({
+ method: 'GET',
+ path: '/api/profile',
+ }).validateSchema(ProfileSchema);
+
+ expect(status).toBe(200);
+ expect(body.name).toBeDefined();
+ expect(body.email).toContain('@');
+ });
+
+ test.skip('should update user profile', async ({ apiRequest }) => {
+ const { status, body } = await apiRequest({
+ method: 'PATCH',
+ path: '/api/profile',
+ body: {
+ name: 'Updated Name',
+ email: 'updated@example.com',
+ },
+ }).validateSchema(ProfileSchema);
+
+ expect(status).toBe(200);
+ expect(body.name).toBe('Updated Name');
+ expect(body.email).toBe('updated@example.com');
+ });
+
+ test.skip('should validate email format', async ({ apiRequest }) => {
+ const { status, body } = await apiRequest({
+ method: 'PATCH',
+ path: '/api/profile',
+ body: { email: 'invalid-email' },
+ });
+
+ expect(status).toBe(400);
+ expect(body.message).toContain('Invalid email format');
+ });
+});
+```
+
+**Lợi ích chính:**
+
+- Trả về `{ status, body }` rõ ràng hơn
+- Có schema validation với Zod
+- Type-safe response body
+- Retry tự động khi gặp 5xx
+- Ít boilerplate hơn
+
+#### E2E tests (`tests/e2e/profile.spec.ts`)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.skip('should edit and save profile', async ({ page }) => {
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('test@example.com');
+ await page.getByLabel('Password').fill('password123');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+
+ await page.goto('/profile');
+
+ await page.getByRole('button', { name: 'Edit Profile' }).click();
+ await page.getByLabel('Name').fill('Updated Name');
+ await page.getByRole('button', { name: 'Save' }).click();
+
+ await expect(page.getByText('Profile updated')).toBeVisible();
+});
+```
+
+TEA cũng sẽ sinh thêm các E2E test cho hiển thị dữ liệu, validation error và hành vi theo acceptance criteria.
+
+#### Implementation Checklist
+
+TEA đồng thời sinh checklist implementation:
+
+```markdown
+## Implementation Checklist
+
+### Backend
+
+- [ ] Create `GET /api/profile` endpoint
+- [ ] Create `PATCH /api/profile` endpoint
+- [ ] Add email validation middleware
+- [ ] Add profile picture upload handling
+- [ ] Write API unit tests
+
+### Frontend
+
+- [ ] Create ProfilePage component
+- [ ] Implement profile form with validation
+- [ ] Add file upload for avatar
+- [ ] Handle API errors gracefully
+- [ ] Add loading states
+
+### Tests
+
+- [x] API test scaffolds generated (`test.skip()`)
+- [x] E2E test scaffolds generated (`test.skip()`)
+- [ ] Activate and run tests during implementation
+```
+
+### 6. Xác minh scaffold pha đỏ
+
+Đây là pha đỏ của TDD, nhưng TEA để test ở `test.skip()` cho đến khi bạn sẵn sàng xử lý từng task. Hãy review file được tạo, bỏ `test.skip()` ở test của task hiện tại và xác nhận test **fail trước** khi implement.
+
+**Playwright:**
+
+```bash
+npx playwright test
+```
+
+**Cypress:**
+
+```bash
+npx cypress run
+```
+
+**Kỳ vọng ban đầu khi mọi scaffold vẫn đang skip:**
+
+```text
+Running 6 tests using 1 worker
+
+ - tests/api/profile.spec.ts:3:3 › should fetch user profile
+ - tests/api/profile.spec.ts:15:3 › should update user profile
+ - tests/e2e/profile.spec.ts:10:3 › should edit and save profile
+
+ 6 skipped
+```
+
+Sau khi bỏ `test.skip()` khỏi test đang làm, test đó phải fail trước. Điều này xác nhận:
+
+- Feature chưa tồn tại đầy đủ
+- Test đang đóng vai trò dẫn dắt implementation
+- Bạn đã có tiêu chí pass/fail rõ
+
+### 7. Implement feature
+
+Quy trình khuyến nghị:
+
+1. Bắt đầu từ API test
+2. Bỏ `test.skip()` ở test API đầu tiên và xác nhận trạng thái RED
+3. Implement đủ để test đó pass
+4. Chuyển sang test kế tiếp
+5. Refactor khi đã có test bảo vệ
+
+### 8. Xác minh test pass
+
+Sau khi implement xong, chạy lại suite.
+
+**Playwright:**
+
+```bash
+npx playwright test
+```
+
+**Cypress:**
+
+```bash
+npx cypress run
+```
+
+**Kỳ vọng đầu ra:**
+
+```text
+Running 6 tests using 1 worker
+
+ ✓ tests/api/profile.spec.ts:3:3 › should fetch user profile (850ms)
+ ✓ tests/api/profile.spec.ts:15:3 › should update user profile (1.2s)
+ ✓ tests/api/profile.spec.ts:30:3 › should validate email format (650ms)
+ ✓ tests/e2e/profile.spec.ts:10:3 › should display current profile (2.1s)
+ ✓ tests/e2e/profile.spec.ts:18:3 › should edit and save profile (3.2s)
+ ✓ tests/e2e/profile.spec.ts:35:3 › should show validation error (1.8s)
+
+ 6 passed (9.8s)
+```
+
+## Bạn sẽ nhận được gì
+
+### Red-phase test scaffold
+
+- API test cho endpoint backend
+- E2E test cho user workflow
+- Component test nếu bạn yêu cầu
+- Tất cả ở dạng `test.skip()` cho tới khi bạn kích hoạt theo task
+
+### Hướng dẫn implement
+
+- Checklist những gì cần xây
+- Acceptance criteria được chuyển thành assertion
+- Nhận diện edge case và error path sớm
+
+### Hỗ trợ luồng TDD
+
+- Test dẫn dắt implementation
+- Tăng tự tin khi refactor
+- Biến test thành “living documentation”
+
+## Mẹo sử dụng
+
+### Hãy chạy Test Design trước
+
+```text
+test-design
+atdd
+```
+
+### Tập trung vào P0/P1 trước
+
+```text
+Generate tests for:
+- P0: Critical path
+- P1: High value
+
+Skip P2/P3 for now
+```
+
+### API trước, E2E sau
+
+Thứ tự nên làm:
+
+1. Sinh API test với `atdd`
+2. Implement backend để API test pass
+3. Sinh hoặc kích hoạt E2E test
+4. Implement frontend để E2E pass
+
+### Browser automation là tùy chọn
+
+Nếu `tea_browser_automation` là `"auto"`, `"cli"` hoặc `"mcp"`, TEA có thể xác minh selector trên browser thật trong lúc làm `atdd`, đặc biệt hữu ích nếu bạn đã có skeleton UI.
+
+Xem thêm: [Configure Browser Automation](/vi-vn/how-to/customization/configure-browser-automation.md)
+
+## Tài liệu liên quan
+
+- [How to Run Test Design](/vi-vn/how-to/workflows/run-test-design.md)
+- [How to Run Automate](/vi-vn/how-to/workflows/run-automate.md)
+- [How to Set Up Test Framework](/vi-vn/how-to/workflows/setup-test-framework.md)
+
+## Hiểu thêm về khái niệm
+
+- [Testing as Engineering](/vi-vn/explanation/testing-as-engineering.md)
+- [Risk-Based Testing](/vi-vn/explanation/risk-based-testing.md)
+- [Test Quality Standards](/vi-vn/explanation/test-quality-standards.md)
+- [Network-First Patterns](/vi-vn/explanation/network-first-patterns.md)
+
+## Tham chiếu
+
+- [Command: \*atdd](/vi-vn/reference/commands.md#atdd)
+- [TEA Configuration](/vi-vn/reference/configuration.md)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/workflows/run-automate.md b/docs/vi-vn/how-to/workflows/run-automate.md
new file mode 100644
index 0000000..966cbf3
--- /dev/null
+++ b/docs/vi-vn/how-to/workflows/run-automate.md
@@ -0,0 +1,601 @@
+---
+title: 'Cách chạy Automate với TEA'
+description: Mở rộng độ bao phủ tự động hóa kiểm thử sau khi implementation hoàn tất bằng workflow automate của TEA
+---
+
+# Cách chạy Automate với TEA
+
+Dùng workflow `automate` của TEA để sinh bộ test đầy đủ cho các tính năng đã tồn tại. Khác với `atdd`, các test này được kỳ vọng sẽ pass ngay vì feature đã có sẵn.
+
+## Khi nào nên dùng
+
+- Feature đã tồn tại và đang hoạt động
+- Muốn bổ sung test coverage cho code hiện có
+- Cần bộ test có thể pass ngay
+- Muốn mở rộng suite hiện hữu
+- Cần thêm test cho code legacy
+
+**Không nên dùng khi:**
+
+- Feature chưa tồn tại, khi đó nên dùng `atdd`
+- Muốn dùng failing test để dẫn dắt phát triển theo TDD
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method
+- Agent TEA đã sẵn sàng
+- Test framework đã được thiết lập xong, nếu chưa thì chạy `framework`
+- Feature đã được implement và đang hoạt động
+
+**Lưu ý:** Tài liệu này dùng ví dụ với Playwright. Nếu dự án dùng Cypress thì câu lệnh và cú pháp sẽ khác.
+
+## Các bước thực hiện
+
+### 1. Nạp agent TEA
+
+Mở một chat mới và chạy:
+
+```text
+tea
+```
+
+### 2. Chạy workflow Automate
+
+```text
+automate
+```
+
+### 3. Cung cấp ngữ cảnh
+
+TEA sẽ hỏi bạn đang kiểm thử cái gì.
+
+#### Tùy chọn A: Chế độ tích hợp với BMad (khuyến nghị)
+
+Nếu bạn đã có artifact của BMad như story, test design hoặc PRD:
+
+**Bạn đang kiểm thử gì?**
+
+```text
+I'm testing the user profile feature we just implemented.
+Story: story-profile-management.md
+Test Design: test-design-epic-1.md
+```
+
+**Tài liệu tham chiếu nên cung cấp:**
+
+- Story file có acceptance criteria
+- Tài liệu test design
+- Phần PRD liên quan tới feature
+- Tech spec nếu có
+
+**Khai báo test hiện có:**
+
+```text
+We have basic tests in tests/e2e/profile-view.spec.ts
+Avoid duplicating that coverage
+```
+
+TEA sẽ phân tích artifact và sinh test để:
+
+- Bao phủ acceptance criteria của story
+- Tuân theo ưu tiên từ test design, ví dụ P0 → P1 → P2
+- Tránh sinh trùng với test hiện có
+- Bổ sung edge case và error scenario phù hợp
+
+#### Tùy chọn B: Chế độ độc lập
+
+Nếu bạn dùng TEA Solo hoặc không có artifact từ BMad:
+
+**Bạn đang kiểm thử gì?**
+
+```text
+TodoMVC React application at https://todomvc.com/examples/react/dist/
+Features: Create todos, mark as complete, filter by status, delete todos
+```
+
+**Scenario cần bao phủ:**
+
+```text
+- Creating todos (happy path)
+- Marking todos as complete/incomplete
+- Filtering (All, Active, Completed)
+- Deleting todos
+- Edge cases (empty input, long text)
+```
+
+TEA sẽ phân tích ứng dụng dựa trên mô tả bạn cung cấp và sinh test tương ứng.
+
+### 4. Chỉ định test level
+
+TEA sẽ hỏi bạn muốn sinh test ở mức nào:
+
+- **E2E tests** - kiểm thử luồng người dùng đầy đủ trên browser
+- **API tests** - kiểm thử endpoint backend, nhanh hơn và ổn định hơn
+- **Component tests** - kiểm thử UI component theo dạng cô lập
+- **Mix** - kết hợp nhiều mức, thường là lựa chọn tốt nhất
+
+**Ví dụ câu trả lời:**
+
+```text
+Generate:
+- API tests for all CRUD operations
+- E2E tests for critical user workflows (P0)
+- Focus on P0 and P1 scenarios
+- Skip P3 (low priority edge cases)
+```
+
+### 5. Review bộ test được sinh ra
+
+TEA sẽ sinh một test suite tương đối đầy đủ theo nhiều test level.
+
+#### API tests (`tests/api/profile.spec.ts`)
+
+**Vanilla Playwright:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Profile API', () => {
+ let authToken: string;
+
+ test.beforeAll(async ({ request }) => {
+ const response = await request.post('/api/auth/login', {
+ data: { email: 'test@example.com', password: 'password123' },
+ });
+ const { token } = await response.json();
+ authToken = token;
+ });
+
+ test('should fetch user profile', async ({ request }) => {
+ const response = await request.get('/api/profile', {
+ headers: { Authorization: `Bearer ${authToken}` },
+ });
+
+ expect(response.ok()).toBeTruthy();
+ const profile = await response.json();
+ expect(profile).toMatchObject({
+ id: expect.any(String),
+ name: expect.any(String),
+ email: expect.any(String),
+ });
+ });
+
+ test('should update profile successfully', async ({ request }) => {
+ const response = await request.patch('/api/profile', {
+ headers: { Authorization: `Bearer ${authToken}` },
+ data: {
+ name: 'Updated Name',
+ bio: 'Test bio',
+ },
+ });
+
+ expect(response.ok()).toBeTruthy();
+ const updated = await response.json();
+ expect(updated.name).toBe('Updated Name');
+ expect(updated.bio).toBe('Test bio');
+ });
+
+ test('should validate email format', async ({ request }) => {
+ const response = await request.patch('/api/profile', {
+ headers: { Authorization: `Bearer ${authToken}` },
+ data: { email: 'invalid-email' },
+ });
+
+ expect(response.status()).toBe(400);
+ const error = await response.json();
+ expect(error.message).toContain('Invalid email');
+ });
+
+ test('should require authentication', async ({ request }) => {
+ const response = await request.get('/api/profile');
+ expect(response.status()).toBe(401);
+ });
+});
+```
+
+**Với Playwright Utils:**
+
+```typescript
+import { test as base, expect } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { createAuthFixtures } from '@seontechnologies/playwright-utils/auth-session';
+import { mergeTests } from '@playwright/test';
+import { z } from 'zod';
+
+const ProfileSchema = z.object({
+ id: z.string(),
+ name: z.string(),
+ email: z.string().email(),
+});
+
+const authFixtureTest = base.extend(createAuthFixtures());
+export const testWithAuth = mergeTests(apiRequestFixture, authFixtureTest);
+
+testWithAuth.describe('Profile API', () => {
+ testWithAuth('should fetch user profile', async ({ apiRequest, authToken }) => {
+ const { status, body } = await apiRequest({
+ method: 'GET',
+ path: '/api/profile',
+ headers: { Authorization: `Bearer ${authToken}` },
+ }).validateSchema(ProfileSchema);
+
+ expect(status).toBe(200);
+ expect(body.name).toBeDefined();
+ });
+
+ testWithAuth('should update profile successfully', async ({ apiRequest, authToken }) => {
+ const { status, body } = await apiRequest({
+ method: 'PATCH',
+ path: '/api/profile',
+ body: { name: 'Updated Name', bio: 'Test bio' },
+ headers: { Authorization: `Bearer ${authToken}` },
+ }).validateSchema(ProfileSchema);
+
+ expect(status).toBe(200);
+ expect(body.name).toBe('Updated Name');
+ });
+
+ testWithAuth('should validate email format', async ({ apiRequest, authToken }) => {
+ const { status, body } = await apiRequest({
+ method: 'PATCH',
+ path: '/api/profile',
+ body: { email: 'invalid-email' },
+ headers: { Authorization: `Bearer ${authToken}` },
+ });
+
+ expect(status).toBe(400);
+ expect(body.message).toContain('Invalid email');
+ });
+});
+```
+
+**Điểm khác biệt chính:**
+
+- Có fixture `authToken` để tái sử dụng token xác thực
+- `apiRequest` trả về `{ status, body }` gọn hơn
+- Có schema validation bằng Zod nên an toàn kiểu dữ liệu hơn
+- Tự động retry với lỗi 5xx
+- Giảm đáng kể boilerplate
+
+#### E2E tests (`tests/e2e/profile.spec.ts`)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('should edit profile', async ({ page }) => {
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('test@example.com');
+ await page.getByLabel('Password').fill('password123');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+
+ await page.goto('/profile');
+ await page.getByRole('button', { name: 'Edit Profile' }).click();
+ await page.getByLabel('Name').fill('New Name');
+ await page.getByRole('button', { name: 'Save' }).click();
+
+ await expect(page.getByText('Profile updated')).toBeVisible();
+});
+```
+
+Ngoài ra, TEA còn sinh thêm test cho validation, edge case, error path tùy theo mức ưu tiên.
+
+#### Fixtures (`tests/support/fixtures/profile.ts`)
+
+**Vanilla Playwright:**
+
+```typescript
+import { test as base, Page } from '@playwright/test';
+
+type ProfileFixtures = {
+ authenticatedPage: Page;
+ testProfile: {
+ name: string;
+ email: string;
+ bio: string;
+ };
+};
+
+export const test = base.extend({
+ authenticatedPage: async ({ page }, use) => {
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('test@example.com');
+ await page.getByLabel('Password').fill('password123');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL(/\/dashboard/);
+
+ await use(page);
+ },
+
+ testProfile: async ({ request }, use) => {
+ const profile = {
+ name: 'Test User',
+ email: 'test@example.com',
+ bio: 'Test bio',
+ };
+
+ await use(profile);
+ },
+});
+```
+
+**Với Playwright Utils:**
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createAuthFixtures } from '@seontechnologies/playwright-utils/auth-session';
+import { mergeTests } from '@playwright/test';
+import { faker } from '@faker-js/faker';
+
+type ProfileFixtures = {
+ testProfile: {
+ name: string;
+ email: string;
+ bio: string;
+ };
+};
+
+const authTest = base.extend(createAuthFixtures());
+const profileTest = base.extend({
+ testProfile: async ({}, use) => {
+ const profile = {
+ name: faker.person.fullName(),
+ email: faker.internet.email(),
+ bio: faker.person.bio(),
+ };
+
+ await use(profile);
+ },
+});
+
+export const test = mergeTests(authTest, profileTest);
+export { expect } from '@playwright/test';
+```
+
+**Cách dùng:**
+
+```typescript
+import { test, expect } from '../support/fixtures/profile';
+
+test('should update profile', async ({ page, authToken, testProfile }) => {
+ await page.goto('/profile');
+});
+```
+
+**Lợi ích chính:**
+
+- Có `authToken` dùng lại giữa các test
+- Dữ liệu động với faker, tránh xung đột
+- Có thể compose fixture bằng `mergeTests`
+- Tái sử dụng tốt giữa nhiều file test
+
+### 6. Review các artifact bổ sung
+
+TEA thường cập nhật thêm:
+
+#### README (`tests/README.md`)
+
+```markdown
+# Test Suite
+
+## Running Tests
+
+### All Tests
+
+npm test
+
+### Specific Levels
+
+npm run test:api
+npm run test:e2e
+npm run test:smoke
+
+### Single File
+
+npx playwright test tests/api/profile.spec.ts
+```
+
+#### Tóm tắt Definition of Done
+
+```markdown
+## Test Quality Checklist
+
+✅ All tests pass on first run
+✅ No hard waits (waitForTimeout)
+✅ No conditionals for flow control
+✅ Assertions are explicit
+✅ Tests clean up after themselves
+✅ Tests can run in parallel
+✅ Execution time < 1.5 minutes per test
+✅ Test files < 300 lines
+```
+
+### 7. Chạy test
+
+Vì feature đã tồn tại, toàn bộ test sinh ra nên pass ngay.
+
+**Playwright:**
+
+```bash
+npx playwright test
+```
+
+**Cypress:**
+
+```bash
+npx cypress run
+```
+
+**Kỳ vọng đầu ra:**
+
+```text
+Running 15 tests using 4 workers
+
+ ✓ tests/api/profile.spec.ts (4 tests) - 2.1s
+ ✓ tests/e2e/profile-workflow.spec.ts (2 tests) - 5.3s
+
+ 15 passed (7.4s)
+```
+
+### 8. Review độ bao phủ
+
+Bạn có thể kiểm tra báo cáo:
+
+```bash
+npx playwright show-report
+npm run test:coverage
+```
+
+Đối chiếu coverage với:
+
+- Acceptance criteria của story
+- Mức ưu tiên từ test design
+- Edge case và error scenario liên quan
+
+## Bạn sẽ nhận được gì
+
+### Test suite tương đối đầy đủ
+
+- **API tests** - nhanh, ổn định, tập trung vào backend
+- **E2E tests** - bao phủ user workflow quan trọng
+- **Component tests** - nếu framework hỗ trợ và bạn yêu cầu
+- **Fixtures** - chia sẻ setup và helper dùng chung
+
+### Component testing theo framework
+
+TEA hỗ trợ component testing bằng tool phù hợp với framework:
+
+| Framework | Tool | Vị trí test |
+| -------------- | ------------------------------ | ------------------------------------------- |
+| **Cypress** | Cypress Component Testing | `tests/component/` |
+| **Playwright** | Vitest + React Testing Library | `tests/component/` hoặc `src/**/*.test.tsx` |
+
+### Các đặc tính chất lượng
+
+- **Network-first patterns** - chờ response thật thay vì timeout
+- **Deterministic tests** - hạn chế flaky
+- **Self-cleaning** - test không để lại dữ liệu bẩn
+- **Parallel-safe** - có thể chạy song song
+
+### Tài liệu đi kèm
+
+- README được cập nhật
+- Giải thích cấu trúc test
+- Checklist chất lượng tương ứng với DoD
+
+## Mẹo sử dụng
+
+### Hãy chạy Test Design trước
+
+```text
+test-design
+automate
+```
+
+Điều này giúp TEA tập trung vào P0/P1 thay vì sinh quá nhiều test giá trị thấp.
+
+### Ưu tiên test level hợp lý
+
+Không phải thứ gì cũng cần E2E.
+
+**Chiến lược thường tốt:**
+
+```text
+- P0: API + E2E
+- P1: API là chính
+- P2: API happy path
+- P3: bỏ qua hoặc thêm sau
+```
+
+**Lý do:**
+
+- API test nhanh hơn E2E rất nhiều
+- API test ổn định hơn
+- E2E nên dành cho luồng người dùng quan trọng
+
+### Tránh coverage trùng lặp
+
+Hãy nói rõ test hiện có:
+
+```text
+We already have tests in:
+- tests/e2e/profile-view.spec.ts
+- tests/api/auth.spec.ts
+
+Don't duplicate that coverage
+```
+
+### Browser automation là tùy chọn bổ sung
+
+Nếu cấu hình `tea_browser_automation` là `"auto"`, `"cli"` hoặc `"mcp"`, TEA có thể dùng browser tool trong `automate` để:
+
+- Healing selector bị hỏng
+- Ghi nhận selector tốt hơn
+- Chụp trace hoặc screenshot làm bằng chứng
+
+Xem thêm: [Configure Browser Automation](/vi-vn/how-to/customization/configure-browser-automation.md)
+
+### Sinh test theo từng vòng
+
+Đừng cố sinh mọi thứ một lần:
+
+1. Sinh P0 trước
+2. Chạy và review
+3. Sinh P1
+4. Chỉ sinh P2 khi thực sự cần
+
+## Vấn đề thường gặp
+
+### Test pass nhưng coverage chưa đủ
+
+**Nguyên nhân:** ngữ cảnh đầu vào chưa đủ chi tiết.
+
+**Cách xử lý:**
+
+```text
+Generate tests for:
+- All acceptance criteria in story-profile.md
+- Error scenarios
+- Edge cases
+```
+
+### Sinh quá nhiều test
+
+**Nguyên nhân:** không giới hạn phạm vi hoặc ưu tiên.
+
+**Cách xử lý:**
+
+```text
+Generate ONLY:
+- P0 and P1 scenarios
+- API tests for all scenarios
+- E2E tests only for critical workflows
+- Skip P2/P3 for now
+```
+
+### Test mới trùng coverage cũ
+
+**Nguyên nhân:** chưa chỉ rõ test đã tồn tại.
+
+**Cách xử lý:** khai báo cụ thể file và phạm vi coverage cũ để TEA tránh lặp.
+
+## Tài liệu liên quan
+
+- [How to Run Test Design](/vi-vn/how-to/workflows/run-test-design.md)
+- [How to Run ATDD](/vi-vn/how-to/workflows/run-atdd.md)
+- [How to Run Test Review](/vi-vn/how-to/workflows/run-test-review.md)
+
+## Hiểu thêm về khái niệm
+
+- [Testing as Engineering](/vi-vn/explanation/testing-as-engineering.md)
+- [Risk-Based Testing](/vi-vn/explanation/risk-based-testing.md)
+- [Test Quality Standards](/vi-vn/explanation/test-quality-standards.md)
+- [Fixture Architecture](/vi-vn/explanation/fixture-architecture.md)
+
+## Tham chiếu
+
+- [Command: \*automate](/vi-vn/reference/commands.md#automate)
+- [TEA Configuration](/vi-vn/reference/configuration.md)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/workflows/run-nfr-assess.md b/docs/vi-vn/how-to/workflows/run-nfr-assess.md
new file mode 100644
index 0000000..53348ee
--- /dev/null
+++ b/docs/vi-vn/how-to/workflows/run-nfr-assess.md
@@ -0,0 +1,420 @@
+---
+title: 'Cách chạy NFR Assessment với TEA'
+description: Xác thực yêu cầu phi chức năng về security, performance, reliability và maintainability bằng TEA
+---
+
+# Cách chạy NFR Assessment với TEA
+
+Dùng workflow `nfr-assess` của TEA để đánh giá yêu cầu phi chức năng bằng cách tiếp cận dựa trên bằng chứng, trải rộng qua security, performance, reliability và maintainability.
+
+## Khi nào nên dùng
+
+- Dự án enterprise có yêu cầu compliance
+- Dự án có ngưỡng NFR rõ ràng và nghiêm ngặt
+- Trước khi phát hành production
+- Khi NFR là yếu tố sống còn của dự án
+- Khi security hoặc performance là yếu tố mission-critical
+
+**Phù hợp nhất cho:**
+
+- Dự án thuộc enterprise track
+- Ngành có compliance cao như tài chính, y tế, chính phủ
+- Ứng dụng lưu lượng lớn
+- Hệ thống nhạy cảm về bảo mật
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method
+- Agent TEA có sẵn
+- NFR đã được định nghĩa trong PRD hoặc requirements doc
+- Có bằng chứng thì tốt hơn, nhưng không bắt buộc
+
+**Lưu ý:** Bạn vẫn có thể chạy `nfr-assess` ngay cả khi chưa có đủ evidence. Khi thiếu dữ liệu, TEA sẽ đánh dấu các hạng mục là `CONCERNS` và ghi rõ cần bổ sung gì.
+
+## Các bước thực hiện
+
+### 1. Chạy workflow NFR Assessment
+
+Mở chat mới và chạy:
+
+```text
+nfr-assess
+```
+
+### 2. Chỉ định nhóm NFR cần đánh giá
+
+TEA sẽ hỏi bạn muốn đánh giá nhóm nào.
+
+| Category | Trọng tâm |
+| ------------------- | ------------------------------------------------------------------------------------------- |
+| **Security** | Authentication, authorization, encryption, vulnerability, security header, input validation |
+| **Performance** | Response time, throughput, resource usage, DB query, frontend load time |
+| **Reliability** | Error handling, recovery, availability, failover, backup |
+| **Maintainability** | Code quality, test coverage, technical debt, documentation, dependency health |
+
+**Ví dụ câu trả lời:**
+
+```text
+Assess:
+- Security (critical for user data)
+- Performance (API must be fast)
+- Reliability (99.9% uptime requirement)
+
+Skip maintainability for now
+```
+
+### 3. Cung cấp threshold cho từng nhóm
+
+TEA sẽ hỏi về ngưỡng chấp nhận cụ thể.
+
+**Nguyên tắc quan trọng: không đoán threshold.** Nếu chưa biết chính xác, hãy yêu cầu TEA đánh dấu `CONCERNS` và ghi nhận cần hỏi stakeholder.
+
+#### Security thresholds
+
+```text
+Requirements:
+- All endpoints require authentication: YES
+- Data encrypted at rest: YES (PostgreSQL TDE)
+- Zero critical vulnerabilities: YES (npm audit)
+- Input validation on all endpoints: YES (Zod schemas)
+- Security headers configured: YES (helmet.js)
+```
+
+#### Performance thresholds
+
+```text
+Requirements:
+- API response time P99: < 200ms
+- API response time P95: < 150ms
+- Throughput: > 1000 requests/second
+- Frontend initial load: < 2 seconds
+- Database query time P99: < 50ms
+```
+
+#### Reliability thresholds
+
+```text
+Requirements:
+- Error handling: All endpoints return structured errors
+- Availability: 99.9% uptime
+- Recovery time: < 5 minutes (RTO)
+- Data backup: Daily automated backups
+- Failover: Automatic with < 30s downtime
+```
+
+#### Maintainability thresholds
+
+```text
+Requirements:
+- Test coverage: > 80%
+- Code quality: SonarQube grade A
+- Documentation: All APIs documented
+- Dependency age: < 6 months outdated
+- Technical debt: < 10% of codebase
+```
+
+### 4. Cung cấp bằng chứng
+
+TEA sẽ hỏi evidence cho từng nhóm yêu cầu.
+
+| Category | Loại evidence | Vị trí ví dụ |
+| --------------- | -------------------- | ------------------------------ |
+| Security | Security scan report | `/reports/security-scan.pdf` |
+| Security | Vulnerability scan | `npm audit`, `snyk test` |
+| Security | Auth test results | report xác thực |
+| Performance | Load test result | `/reports/k6-load-test.json` |
+| Performance | APM data | Datadog, New Relic |
+| Reliability | Error rate metric | dashboard giám sát |
+| Reliability | Uptime data | StatusPage, PagerDuty |
+| Maintainability | Coverage report | `/reports/coverage/index.html` |
+| Maintainability | Code quality | SonarQube |
+
+**Ví dụ câu trả lời:**
+
+```text
+Evidence:
+- Security: npm audit results (clean), auth tests 15/15 passing
+- Performance: k6 load test at /reports/k6-results.json
+- Reliability: Error rate 0.01% in staging (logs in Datadog)
+
+Don't have:
+- Uptime data (new system, no baseline)
+- Mark as CONCERNS and request monitoring setup
+```
+
+### 5. Review báo cáo NFR
+
+TEA sẽ sinh báo cáo đánh giá đầy đủ hơn, ví dụ:
+
+```markdown
+# Non-Functional Requirements Assessment
+
+**Date:** 2026-01-13
+**Epic:** User Profile Management
+**Release:** v1.2.0
+**Overall Decision:** CONCERNS ⚠️
+
+## Executive Summary
+
+| Category | Status | Critical Issues |
+| --------------- | ----------- | --------------- |
+| Security | PASS ✅ | 0 |
+| Performance | CONCERNS ⚠️ | 2 |
+| Reliability | PASS ✅ | 0 |
+| Maintainability | PASS ✅ | 0 |
+```
+
+### Ví dụ kết luận về Security
+
+- Authentication được enforce
+- Không có critical vulnerability
+- Input validation đầy đủ
+- Security header được cấu hình
+
+=> **PASS**
+
+### Ví dụ kết luận về Performance
+
+| Metric | Target | Actual | Status |
+| ---------------- | ---------- | ------- | ---------- |
+| API response P99 | < 200ms | 350ms | ❌ Exceeds |
+| API response P95 | < 150ms | 180ms | ⚠️ Exceeds |
+| Throughput | > 1000 rps | 850 rps | ⚠️ Below |
+| Frontend load | < 2s | 1.8s | ✅ Met |
+| DB query P99 | < 50ms | 85ms | ❌ Exceeds |
+
+**Vấn đề 1: P99 latency vượt ngưỡng**
+
+- Đo được: 350ms
+- Nguyên nhân gốc: DB query chưa tối ưu
+- Mitigation:
+ - thêm index
+ - xử lý N+1 query
+ - chạy lại load test
+
+**Vấn đề 2: Throughput dưới ngưỡng**
+
+- Đo được: 850 rps
+- Nguyên nhân gốc: pool kết nối quá nhỏ
+- Mitigation:
+ - tăng `max_connections`
+ - thêm connection pooling
+ - chạy lại load test
+
+### Ví dụ kết luận về Reliability
+
+- Structured error đầy đủ
+- Uptime đạt 99.95%
+- Recovery time đạt 3 phút
+- Backup tự động hằng ngày
+- Failover đạt 15s
+
+=> **PASS**
+
+### Ví dụ kết luận về Maintainability
+
+- Coverage trên 80%
+- SonarQube grade A
+- API docs đầy đủ
+- Dependency age chấp nhận được
+- Technical debt trong ngưỡng
+
+=> **PASS**
+
+## Overall Gate Decision
+
+### Decision: CONCERNS ⚠️
+
+**Lý do:**
+
+- Không có blocker tuyệt đối
+- Có concern ở performance
+- Có mitigation plan rõ ràng
+- Security, reliability và maintainability đều đạt
+
+````
+
+## Bạn sẽ nhận được gì
+
+### NFR assessment report
+
+- Phân tích theo từng nhóm
+- So sánh target và actual
+- Gắn evidence cho từng yêu cầu
+- Chỉ ra issue và root cause
+
+### Gate decision
+
+- **PASS** ✅ - đạt toàn bộ NFR quan trọng
+- **CONCERNS** ⚠️ - chưa đạt một số ngưỡng nhưng đã có mitigation plan
+- **FAIL** ❌ - có blocker phi chức năng nghiêm trọng
+- **WAIVED** ⏭️ - có phê duyệt kinh doanh đi kèm chấp nhận rủi ro
+
+### Mitigation plan
+
+- Hành động cụ thể
+- Chủ sở hữu
+- Deadline
+- Tiêu chí để re-assess
+
+### Monitoring plan
+
+- Cách theo dõi sau release
+- Alert threshold
+- Nhịp review
+
+## Mẹo sử dụng
+
+### Chạy NFR assessment sớm
+
+**Phase 2 (Enterprise):**
+
+- Xác định NFR sớm
+- Lập kế hoạch cho performance testing
+- Dự trù security audit
+- Chuẩn bị monitoring
+
+**Phase 4 hoặc release gate:**
+
+- Chạy lại để xác nhận hệ thống thực sự đạt ngưỡng
+
+### Đừng đoán threshold
+
+**Không nên:**
+
+```text
+API response time should probably be under 500ms
+```
+
+**Nên làm:**
+
+```text
+Mark as CONCERNS - Request threshold from stakeholders
+```
+
+### Thu thập evidence trước khi chạy
+
+**Security:**
+
+```bash
+npm audit
+snyk test
+npm run test:security
+```
+
+**Performance:**
+
+```bash
+npm run test:load
+npm run test:lighthouse
+npm run test:db-performance
+```
+
+**Maintainability:**
+
+```bash
+npm run test:coverage
+npm run lint
+npm outdated
+```
+
+### Dùng dữ liệu thật, không dùng cảm giác
+
+**Không nên:**
+
+```text
+System is probably fast enough
+Security seems fine
+```
+
+**Nên:**
+
+```text
+Load test results show P99 = 350ms
+npm audit shows 0 vulnerabilities
+Test coverage report shows 85%
+```
+
+### Ghi waiver thật rõ
+
+Nếu business chấp nhận release dù còn concern, cần ghi:
+
+- Ai phê duyệt
+- Vì sao chấp nhận
+- Điều kiện đi kèm
+- Rủi ro được chấp nhận
+- Kế hoạch khắc phục sau đó
+
+### Re-assess sau khi sửa
+
+Quy trình nên là:
+
+1. Sửa issue
+2. Chạy lại load test/security test/metric liên quan
+3. Chạy lại `nfr-assess`
+4. Xác nhận trạng thái mới
+
+## Vấn đề thường gặp
+
+### Không có evidence
+
+**Cách xử lý:**
+
+- Đánh dấu `CONCERNS`
+- Ghi rõ còn thiếu evidence gì
+- Thiết lập test hoặc monitoring trước lần đánh giá tiếp theo
+
+### Threshold quá khắt khe
+
+Nếu stakeholder đưa ra threshold không thực tế:
+
+- Dùng dữ liệu thật để phản biện
+- Đề xuất threshold phù hợp hơn
+- Giải thích theo bối cảnh kỹ thuật và tải hệ thống
+
+### Đánh giá mất quá nhiều thời gian
+
+Hãy ưu tiên:
+
+1. Security
+2. Performance
+3. Reliability
+4. Maintainability
+
+Không nhất thiết phải đánh giá mọi nhóm ở cùng một lần đầu tiên.
+
+### CONCERNS hay FAIL?
+
+**CONCERNS** khi:
+
+- Vấn đề có thật nhưng chưa tới mức blocker
+- Có mitigation plan
+- Có thể monitor và quản trị rủi ro
+
+**FAIL** khi:
+
+- Có lỗ hổng bảo mật nghiêm trọng
+- Hệ thống không dùng được
+- Có nguy cơ mất dữ liệu
+- Không có phương án giảm thiểu hợp lý
+
+## Tài liệu liên quan
+
+- [How to Run Trace](/vi-vn/how-to/workflows/run-trace.md)
+- [How to Run Test Review](/vi-vn/how-to/workflows/run-test-review.md)
+- [Run TEA for Enterprise](/vi-vn/how-to/brownfield/use-tea-for-enterprise.md)
+
+## Hiểu thêm về khái niệm
+
+- [Risk-Based Testing](/vi-vn/explanation/risk-based-testing.md)
+- [TEA Overview](/vi-vn/explanation/tea-overview.md)
+
+## Tham chiếu
+
+- [Command: *nfr-assess](/vi-vn/reference/commands.md#nfr-assess)
+- [TEA Configuration](/vi-vn/reference/configuration.md)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
+````
diff --git a/docs/vi-vn/how-to/workflows/run-test-design.md b/docs/vi-vn/how-to/workflows/run-test-design.md
new file mode 100644
index 0000000..a69ccae
--- /dev/null
+++ b/docs/vi-vn/how-to/workflows/run-test-design.md
@@ -0,0 +1,167 @@
+---
+title: 'Cách chạy Test Design với TEA'
+description: Cách tạo test plan toàn diện bằng workflow test-design của TEA
+---
+
+Sử dụng workflow `test-design` của TEA để tạo test plan toàn diện với risk assessment và coverage strategy.
+
+## Khi nào nên dùng
+
+**System-level (Phase 3):**
+
+- Sau khi architecture hoàn tất
+- Trước implementation-readiness gate
+- Khi cần đánh giá testability của kiến trúc
+
+**Epic-level (Phase 4):**
+
+- Ở đầu mỗi epic
+- Trước khi implement stories trong epic đó
+- Khi cần xác định nhu cầu kiểm thử riêng cho epic
+
+:::note[Điều kiện tiên quyết]
+
+- Đã cài BMad Method
+- Có TEA agent
+- Với system-level: architecture document đã hoàn chỉnh
+- Với epic-level: epic đã được định nghĩa cùng stories
+ :::
+
+## Các bước thực hiện
+
+### 1. Nạp TEA agent
+
+Bắt đầu một chat mới và nạp TEA.
+
+### 2. Chạy workflow test-design
+
+```text
+test-design
+```
+
+### 3. Chọn mode
+
+TEA sẽ hỏi bạn muốn:
+
+- **System-level** - review testability ở mức kiến trúc
+- **Epic-level** - lập kế hoạch test cho một epic cụ thể
+
+### 4. Cung cấp context
+
+Với **system-level**:
+
+- trỏ tới architecture document
+- tham chiếu ADR nếu có
+- cung cấp PRD hoặc các NFR liên quan
+
+Với **epic-level**:
+
+- chỉ rõ epic đang chuẩn bị
+- tham chiếu file epic có stories
+- nêu acceptance criteria, dependency và integration risk nếu có
+
+### 5. Review output
+
+TEA sẽ sinh một hoặc nhiều tài liệu test design tùy mode.
+
+## Bạn sẽ nhận được gì
+
+### Output system-level: hai tài liệu riêng
+
+TEA tạo **hai tài liệu tách biệt** trong mode system-level:
+
+1. **`test-design-architecture.md`**
+ - dành cho team Architecture/Dev
+ - nêu concern kiến trúc, gap về testability và yêu cầu NFR
+ - có Quick Guide với các mức như blocker, high priority, info only
+ - có risk assessment và mitigation cho rủi ro cao
+
+2. **`test-design-qa.md`**
+ - dành cho team QA
+ - đóng vai trò như recipe thực thi test
+ - có test environment requirements
+ - có testability assessment
+ - có test levels strategy
+ - có coverage plan P0/P1/P2/P3 với scenario cụ thể
+ - có Sprint 0 setup requirements
+ - có tóm tắt NFR readiness
+
+### Vì sao lại chia làm hai tài liệu
+
+- Team architecture có thể quét blocker rất nhanh
+- Team QA có tài liệu hành động được, theo kiểu step-by-step
+- Tránh trùng lặp
+- Tách bạch rõ "cần giao gì" và "sẽ test như thế nào"
+
+### Output epic-level: một tài liệu
+
+**`test-design-epic-N.md`**
+
+Tài liệu này thường gồm:
+
+- risk assessment cho epic
+- mức ưu tiên test P0-P3
+- coverage plan
+- regression hotspot nếu là brownfield
+- integration risk
+- mitigation strategy
+
+## Test Design theo từng track
+
+| Track | Trọng tâm Phase 3 | Trọng tâm Phase 4 |
+| -------------- | ------------------------------------ | -------------------------------------- |
+| **Greenfield** | review testability ở mức hệ thống | risk assessment và test plan theo epic |
+| **Brownfield** | system-level + baseline test hiện có | hotspot regression và integration risk |
+| **Enterprise** | testability có xét compliance | security/performance/compliance focus |
+
+## Ví dụ
+
+**System-level (hai tài liệu):**
+
+- `cluster-search-test-design-architecture.md`
+- `cluster-search-test-design-qa.md`
+
+**Pattern quan trọng:**
+
+- Tài liệu architecture sẽ chỉ ra risk và blocker
+- Tài liệu QA sẽ chỉ ra test scenario và trình tự thực thi
+- Hai tài liệu tham chiếu chéo lẫn nhau, không lặp lại nội dung
+
+## Mẹo thực hành
+
+- Chạy **system-level ngay sau architecture** để phát hiện gap testability sớm
+- Chạy **epic-level ở đầu mỗi epic** để không viết test theo cảm tính
+- Nếu ADR thay đổi, cập nhật lại test design
+- Dùng output của `test-design` để feed cho `atdd` và `automate`
+- Team architecture nên review tài liệu architecture
+- Team QA nên dùng tài liệu QA như implementation guide
+
+## Câu hỏi QC nên chuẩn bị trước khi chạy
+
+- Luồng nào chạm trực tiếp tới giá trị nghiệp vụ?
+- Tích hợp nào có xác suất fail cao?
+- Phần nào khó quan sát hoặc khó mô phỏng?
+- Có role, permission, dữ liệu hay điều kiện môi trường đặc biệt nào không?
+- Với brownfield, hotspot regression nằm ở đâu?
+
+## Bước tiếp theo
+
+Sau `test-design`, thường sẽ tiếp tục theo một trong các hướng:
+
+1. **Setup Test Framework** nếu hạ tầng test chưa có
+2. **Implementation Readiness** nếu đang ở system-level
+3. **Story Implementation** nếu đang ở epic-level
+4. **ATDD** nếu muốn sinh failing tests trước khi dev
+5. **Automate** nếu muốn mở rộng coverage sau implementation
+
+## Tài liệu liên quan
+
+- [Setup Test Framework](/docs/vi-vn/how-to/workflows/setup-test-framework.md)
+- [Run ATDD](/docs/vi-vn/how-to/workflows/run-atdd.md)
+- [Run Automate](/docs/vi-vn/how-to/workflows/run-automate.md)
+- [Risk-Based Testing](/docs/vi-vn/explanation/risk-based-testing.md)
+- [TEA Overview](/docs/vi-vn/explanation/tea-overview.md)
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/workflows/run-test-review.md b/docs/vi-vn/how-to/workflows/run-test-review.md
new file mode 100644
index 0000000..98157ba
--- /dev/null
+++ b/docs/vi-vn/how-to/workflows/run-test-review.md
@@ -0,0 +1,440 @@
+---
+title: 'Cách chạy Test Review với TEA'
+description: Audit chất lượng test bằng knowledge base của TEA và nhận báo cáo chấm điểm từ 0-100
+---
+
+# Cách chạy Test Review với TEA
+
+Dùng workflow `test-review` của TEA để audit chất lượng bộ test bằng chấm điểm khách quan và feedback có thể hành động ngay. TEA sẽ review test dựa trên knowledge base gồm các best practice của hệ thống.
+
+**Lưu ý quan trọng:** `test-review` **không chấm coverage theo yêu cầu**. Nếu bạn cần phân tích coverage, map requirement với test hoặc ra gate decision theo coverage, hãy dùng `trace`.
+
+## Khi nào nên dùng
+
+- Muốn đánh giá chất lượng test một cách khách quan
+- Cần quality metric cho quality gate
+- Chuẩn bị triển khai production
+- Review test do team viết
+- Audit test do AI sinh ra
+- Onboard thành viên mới bằng cách cho họ xem pattern tốt
+- Kiểm tra chất lượng migration trước khi mở rộng coverage
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method
+- Agent TEA đã sẵn sàng
+- Đã có test để review
+- Test framework đã được cấu hình
+
+## Các bước thực hiện
+
+### 1. Nạp agent TEA
+
+Mở một chat mới và chạy:
+
+```text
+tea
+```
+
+### 2. Chạy workflow Test Review
+
+```text
+test-review
+```
+
+### 3. Chỉ định phạm vi review
+
+TEA sẽ hỏi bạn muốn review phần nào.
+
+#### Tùy chọn A: Một file đơn lẻ
+
+```text
+tests/e2e/checkout.spec.ts
+```
+
+**Phù hợp khi:**
+
+- Review một test file đang lỗi
+- Muốn có feedback nhanh cho test mới
+- Học từ một ví dụ cụ thể
+
+#### Tùy chọn B: Một thư mục
+
+```text
+tests/e2e/
+```
+
+**Phù hợp khi:**
+
+- Review toàn bộ suite E2E
+- So sánh chất lượng giữa các file
+- Tìm pattern lỗi lặp lại
+
+#### Tùy chọn C: Toàn bộ suite
+
+```text
+tests/
+```
+
+**Phù hợp khi:**
+
+- Kiểm tra chất lượng ở release gate
+- Audit toàn diện
+- Thiết lập baseline metric
+
+### 4. Review báo cáo chất lượng
+
+TEA sẽ sinh báo cáo chấm điểm khá đầy đủ.
+
+#### Cấu trúc báo cáo (`test-review.md`)
+
+````markdown
+# Test Quality Review Report
+
+**Date:** 2026-01-13
+**Scope:** tests/e2e/
+**Overall Score:** 76/100
+
+## Summary
+
+- **Tests Reviewed:** 12
+- **Passing Quality:** 9 tests (75%)
+- **Needs Improvement:** 3 tests (25%)
+- **Critical Issues:** 2
+- **Recommendations:** 6
+
+## Critical Issues
+
+### 1. Hard Waits Detected
+
+**File:** `tests/e2e/checkout.spec.ts:45`
+**Issue:** Using `page.waitForTimeout(3000)`
+**Impact:** Test is flaky and unnecessarily slow
+**Severity:** Critical
+
+**Current Code:**
+
+```typescript
+await page.click('button[type="submit"]');
+await page.waitForTimeout(3000); // ❌ Hard wait
+await expect(page.locator('.success')).toBeVisible();
+```
+````
+
+**Fix:**
+
+```typescript
+await page.click('button[type="submit"]');
+await page.waitForResponse((resp) => resp.url().includes('/api/checkout') && resp.ok());
+await expect(page.locator('.success')).toBeVisible();
+```
+
+**Why This Matters:**
+
+- Hard wait là timeout cố định, không chờ điều kiện thật
+- Test dễ fail ngẫu nhiên trên máy chậm hoặc CI
+- Làm test chậm ngay cả khi response rất nhanh
+- Network-first pattern đáng tin cậy hơn
+
+---
+
+### 2. Conditional Flow Control
+
+**File:** `tests/e2e/profile.spec.ts:28`
+**Issue:** Dùng `if/else` để xử lý phần tử tùy chọn
+**Impact:** Hành vi test không deterministic
+**Severity:** Critical
+
+**Current Code:**
+
+```typescript
+if (await page.locator('.banner').isVisible()) {
+ await page.click('.dismiss');
+}
+```
+
+**Fix:**
+
+```typescript
+await expect(page.locator('.banner')).toBeVisible();
+await page.click('.dismiss');
+```
+
+Hoặc tách thành hai test độc lập cho hai trạng thái khác nhau.
+
+---
+
+### 1. Extract Repeated Setup
+
+**File:** `tests/e2e/profile.spec.ts`
+**Issue:** Lặp lại login code ở mọi test
+**Severity:** Medium
+**Impact:** Tăng chi phí bảo trì
+
+**Fix (Vanilla Playwright):**
+
+```typescript
+import { test as base, Page } from '@playwright/test';
+
+export const test = base.extend<{ authenticatedPage: Page }>({
+ authenticatedPage: async ({ page }, use) => {
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('test@example.com');
+ await page.getByLabel('Password').fill('password');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL(/\/dashboard/);
+ await use(page);
+ },
+});
+```
+
+**Tốt hơn khi dùng Playwright Utils:**
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createAuthFixtures } from '@seontechnologies/playwright-utils/auth-session';
+
+export const test = base.extend(createAuthFixtures());
+```
+
+### 2. Add Network Assertions
+
+**File:** `tests/e2e/api-calls.spec.ts`
+**Issue:** Không xác minh API response
+**Severity:** Low
+**Impact:** Có thể bỏ sót lỗi backend
+
+### 3. Improve Test Names
+
+**File:** `tests/e2e/checkout.spec.ts`
+**Issue:** Tên test mơ hồ
+**Severity:** Low
+**Impact:** Khó đọc và khó review
+
+## Quality Scores by Category
+
+| Category | Score | Target | Status |
+| ------------------- | ----- | ------ | -------------------- |
+| **Determinism** | 72 | 80 | ⚠️ Needs Improvement |
+| **Isolation** | 88 | 80 | ✅ Good |
+| **Maintainability** | 70 | 80 | ⚠️ Needs Improvement |
+| **Performance** | 60 | 80 | ❌ Critical |
+
+## Files Reviewed
+
+| File | Score | Issues | Status |
+| ---------------------------- | ------ | ------ | -------------------- |
+| `tests/e2e/checkout.spec.ts` | 65/100 | 4 | ❌ Needs Work |
+| `tests/e2e/profile.spec.ts` | 72/100 | 3 | ⚠️ Needs Improvement |
+| `tests/e2e/search.spec.ts` | 88/100 | 1 | ✅ Good |
+| `tests/api/profile.spec.ts` | 92/100 | 0 | ✅ Excellent |
+
+```
+
+## Next Steps
+
+1. Remove hard waits in `checkout.spec.ts`
+2. Fix conditional logic in `profile.spec.ts`
+3. Improve setup reuse, network assertions, and naming
+```
+
+## Cách hiểu điểm số
+
+### Điểm số có ý nghĩa gì?
+
+| Khoảng điểm | Diễn giải | Hành động |
+| ----------- | -------------- | ----------------------------------------------------- |
+| **90-100** | Rất tốt | Hầu như không cần chỉnh thêm, sẵn sàng cho production |
+| **80-89** | Tốt | Chỉ nên cải thiện nhỏ |
+| **70-79** | Chấp nhận được | Nên xử lý các recommendation trước release |
+| **60-69** | Cần cải thiện | Phải sửa critical issue và áp dụng recommendation |
+| **< 60** | Nghiêm trọng | Cần refactor đáng kể |
+
+### Tiêu chí chấm điểm
+
+**Determinism (30%)**
+
+- Test cần cho ra cùng một kết quả ở mỗi lần chạy
+- Không flaky
+- Không phụ thuộc môi trường
+
+**Isolation (30%)**
+
+- Test không phụ thuộc lẫn nhau
+- Chạy được ở bất kỳ thứ tự nào
+- Có dọn dẹp sau test
+
+**Maintainability (25%)**
+
+- Dễ đọc, dễ bảo trì
+- Kích thước phù hợp
+- Tên rõ ràng
+
+**Performance (15%)**
+
+- Thời gian chạy nhanh
+- Selector hiệu quả
+- Không có wait không cần thiết
+
+**Coverage**
+
+- Không được chấm trong `test-review`
+- Dùng `trace` để đánh giá coverage, traceability và gate
+
+## Bạn sẽ nhận được gì
+
+### Quality report
+
+- Overall score từ 0-100
+- Điểm theo từng hạng mục
+- Breakdown theo từng file
+
+### Critical issues
+
+- Chỉ rõ line number
+- Có ví dụ code hiện tại và hướng sửa
+- Giải thích vì sao vấn đề này quan trọng
+- Có đánh giá mức ảnh hưởng
+
+### Recommendations
+
+- Đề xuất cụ thể có thể áp dụng được
+- Ví dụ code
+- Mức ưu tiên và severity
+
+### Next steps
+
+- Việc cần làm ngay
+- Cải tiến ngắn hạn
+- Mục tiêu chất lượng dài hạn
+
+## Mẹo sử dụng
+
+### Review trước release
+
+Hãy đưa test review vào release checklist:
+
+```markdown
+## Quality Checklist (Test-Review)
+
+- [ ] All tests passing
+- [ ] Test-review quality score > 80
+- [ ] Critical issues resolved
+- [ ] Performance within budget
+```
+
+### Review sau khi AI sinh test
+
+Quy trình khuyến nghị:
+
+1. Chạy `atdd` hoặc `automate`
+2. Chạy `test-review` trên test vừa sinh
+3. Sửa critical issue
+4. Mới commit
+
+### Đặt quality gate
+
+Ví dụ dùng điểm chất lượng làm gate trong CI:
+
+```yaml
+- name: Review test quality
+ run: |
+ if [ $SCORE -lt 80 ]; then
+ echo "Test-review quality gate below threshold"
+ exit 1
+ fi
+```
+
+Coverage gate vẫn thuộc về `trace`, không phải `test-review`.
+
+### Review định kỳ
+
+- **Mỗi story:** tùy chọn
+- **Mỗi epic:** nên làm
+- **Mỗi release:** rất nên làm
+- **Hàng quý:** audit toàn bộ suite
+
+### Review theo phạm vi nhỏ
+
+Nếu suite lớn, hãy chia nhỏ:
+
+- Tuần 1: E2E
+- Tuần 2: API
+- Tuần 3: component test
+- Tuần 4: áp dụng fix trên toàn bộ suite
+
+## Vấn đề thường gặp
+
+### Điểm Determinism thấp
+
+**Dấu hiệu:**
+
+- Test fail ngẫu nhiên
+- “Works on my machine”
+- CI lỗi nhưng local không tái hiện được
+
+**Nguyên nhân thường gặp:**
+
+- `waitForTimeout`
+- `if/else` hoặc `try/catch` để điều khiển flow
+- Thiếu network-first pattern
+
+### Điểm Performance thấp
+
+**Dấu hiệu:**
+
+- Mỗi test chạy quá lâu
+- Suite mất hàng giờ
+- CI timeout
+
+**Nguyên nhân thường gặp:**
+
+- Wait không cần thiết
+- Selector kém hiệu quả
+- Không dùng parallelization
+- Setup quá nặng ở mỗi test
+
+### Điểm Isolation thấp
+
+**Dấu hiệu:**
+
+- Test fail khi đổi thứ tự chạy
+- Fail khi chạy song song
+- Dữ liệu test va chạm nhau
+
+**Nguyên nhân thường gặp:**
+
+- Shared global state
+- Không dọn dữ liệu sau test
+- Dữ liệu hard-code
+- Database không reset phù hợp
+
+### “Có quá nhiều issue để sửa”
+
+Đừng cố sửa tất cả một lúc:
+
+1. Sửa toàn bộ critical issue trước
+2. Áp dụng 3 recommendation quan trọng nhất
+3. Chạy lại `test-review`
+4. Lặp tiếp
+
+## Tài liệu liên quan
+
+- [How to Run ATDD](/vi-vn/how-to/workflows/run-atdd.md)
+- [How to Run Automate](/vi-vn/how-to/workflows/run-automate.md)
+- [How to Run Trace](/vi-vn/how-to/workflows/run-trace.md)
+
+## Hiểu thêm về khái niệm
+
+- [Test Quality Standards](/vi-vn/explanation/test-quality-standards.md)
+- [Network-First Patterns](/vi-vn/explanation/network-first-patterns.md)
+- [Fixture Architecture](/vi-vn/explanation/fixture-architecture.md)
+
+## Tham chiếu
+
+- [Command: \*test-review](/vi-vn/reference/commands.md#test-review)
+- [Knowledge Base Index](/vi-vn/reference/knowledge-base.md)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/workflows/run-trace.md b/docs/vi-vn/how-to/workflows/run-trace.md
new file mode 100644
index 0000000..14a0b99
--- /dev/null
+++ b/docs/vi-vn/how-to/workflows/run-trace.md
@@ -0,0 +1,576 @@
+---
+title: 'Cách chạy Trace với TEA'
+description: Ánh xạ requirement, spec hoặc user journey với test và đưa ra quality gate decision bằng workflow trace của TEA
+---
+
+# Cách chạy Trace với TEA
+
+Dùng workflow `trace` của TEA để làm coverage traceability và quality gate decision. Đây là workflow gồm **2 phase**:
+
+- **Phase 1**: phân tích coverage
+- **Phase 2**: đưa ra quyết định go/no-go
+
+Workflow này sẽ tự resolve coverage oracle tốt nhất có thể: ưu tiên formal requirements, sau đó đến contract/spec artifact, rồi external pointer có thể truy được, và cuối cùng là synthetic journey suy luận từ source nếu là brownfield.
+
+## Khi nào nên dùng
+
+### Phase 1: Coverage Traceability
+
+- Map requirement hoặc inferred journey với test đã implement
+- Tìm khoảng trống coverage
+- Ưu tiên test còn thiếu
+- Refresh coverage sau mỗi story hoặc epic
+
+### Phase 2: Quality Gate Decision
+
+- Đưa ra quyết định go/no-go cho release
+- Kiểm tra coverage có đạt ngưỡng không
+- Ghi lại gate decision bằng bằng chứng
+- Hỗ trợ waiver được business chấp thuận
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method
+- Agent TEA có sẵn
+- Có requirements/spec hoặc source tree đủ để phân tích
+- Đã có test được implement
+- Với brownfield: codebase hiện có và có test
+
+## Các bước thực hiện
+
+### 1. Chạy workflow Trace
+
+```text
+trace
+```
+
+### 2. Chỉ định phase
+
+TEA sẽ hỏi bạn đang chạy phase nào.
+
+**Phase 1: Coverage Traceability**
+
+- Phân tích coverage
+- Tìm gap
+- Sinh recommendation
+
+**Phase 2: Quality Gate Decision**
+
+- Đưa ra `PASS`, `CONCERNS`, `FAIL`, hoặc `WAIVED`
+- Yêu cầu đã hoàn tất Phase 1
+
+**Luồng phổ biến:** chạy Phase 1 trước, review gap, sau đó chạy Phase 2 để ra gate decision.
+
+---
+
+## Phase 1: Coverage Traceability
+
+### 3. Cung cấp coverage source
+
+TEA sẽ tìm coverage oracle tốt nhất hiện có.
+
+| Nguồn | Ví dụ | Phù hợp nhất cho |
+| --------------- | -------------------------------- | -------------------------- |
+| **Story file** | `story-profile-management.md` | coverage cho một story |
+| **Test design** | `test-design-epic-1.md` | coverage cho một epic |
+| **PRD** | `PRD.md` | coverage ở mức hệ thống |
+| **Spec** | `openapi.yaml` | coverage cho API/contract |
+| **Pointer** | `requirements.md -> tracker/doc` | hệ thống record bên ngoài |
+| **Synthetic** | inferred from `src/` | fallback cho brownfield UI |
+| **Multiple** | nhiều nguồn cùng lúc | phân tích toàn diện |
+
+**Ví dụ trả lời:**
+
+```text
+Coverage sources:
+- story-profile-management.md (acceptance criteria)
+- test-design-epic-1.md (test priorities)
+```
+
+Nếu không có bất kỳ nguồn nào và `allow_synthetic_oracle` được bật, TEA sẽ suy luận provisional journey từ route/page/screen, user action chính, auth flow và UI state quan trọng, rồi trace test theo các journey này với mức confidence rõ ràng.
+
+### 4. Chỉ định vị trí test
+
+TEA sẽ hỏi test nằm ở đâu.
+
+**Ví dụ:**
+
+```text
+Test location: tests/
+Include:
+- tests/api/
+- tests/e2e/
+```
+
+### 5. Chỉ định focus area nếu cần
+
+**Ví dụ:**
+
+```text
+Focus on:
+- Profile CRUD operations
+- Validation scenarios
+- Authorization checks
+```
+
+### 6. Review coverage matrix
+
+TEA sẽ sinh một traceability matrix khá đầy đủ.
+
+#### Ví dụ `traceability-matrix.md`
+
+```markdown
+# Requirements Traceability Matrix
+
+**Date:** 2026-01-13
+**Scope:** Epic 1 - User Profile Management
+**Phase:** Phase 1 (Traceability Analysis)
+
+## Coverage Summary
+
+| Metric | Count | Percentage |
+| ---------------------- | ----- | ---------- |
+| **Total Requirements** | 15 | 100% |
+| **Full Coverage** | 11 | 73% |
+| **Partial Coverage** | 3 | 20% |
+| **No Coverage** | 1 | 7% |
+
+### By Priority
+
+| Priority | Total | Covered | Percentage |
+| -------- | ----- | ------- | ------------------ |
+| **P0** | 5 | 5 | 100% ✅ |
+| **P1** | 6 | 5 | 83% ⚠️ |
+| **P2** | 3 | 1 | 33% ⚠️ |
+| **P3** | 1 | 0 | 0% ✅ (acceptable) |
+```
+
+#### Ví dụ traceability chi tiết
+
+```markdown
+### ✅ Requirement 1: User can view their profile (P0)
+
+**Acceptance Criteria:**
+
+- User navigates to /profile
+- Profile displays name, email, avatar
+- Data is current (not cached)
+
+**Test Coverage:** FULL ✅
+
+**Tests:**
+
+- `tests/e2e/profile-view.spec.ts:15`
+- `tests/api/profile.spec.ts:8`
+```
+
+```markdown
+### ⚠️ Requirement 2: User can edit profile (P0)
+
+**Acceptance Criteria:**
+
+- User clicks "Edit Profile"
+- Can modify name, email, bio
+- Can upload avatar
+- Changes are persisted
+- Success message shown
+
+**Test Coverage:** PARTIAL ⚠️
+
+**Missing Coverage:**
+
+- Bio field not tested
+- Avatar upload not tested
+
+**Gap Severity:** HIGH
+```
+
+```markdown
+### ❌ Requirement 15: Profile export as PDF (P2)
+
+**Test Coverage:** NONE ❌
+
+**Recommendation:** Add in next iteration (not blocking for release)
+```
+
+### 7. Review gap prioritization
+
+TEA thường nhóm gap thành:
+
+#### Critical Gaps
+
+| Gap | Requirement | Priority | Risk | Recommendation |
+| --- | ------------------------ | -------- | ---- | ------------------- |
+| 1 | Bio field not tested | P0 | High | Add E2E + API tests |
+| 2 | Avatar upload not tested | P0 | High | Add E2E + API tests |
+
+#### Non-Critical Gaps
+
+| Gap | Requirement | Priority | Risk | Recommendation |
+| --- | ------------------------- | -------- | ---- | ------------------- |
+| 3 | Profile export not tested | P2 | Low | Add in v1.3 release |
+
+### 8. Review recommendation
+
+TEA có thể gợi ý test cụ thể cần thêm.
+
+**Ví dụ:**
+
+```typescript
+test('should edit bio field', async ({ page }) => {
+ await page.goto('/profile');
+ await page.getByRole('button', { name: 'Edit' }).click();
+ await page.getByLabel('Bio').fill('New bio text');
+ await page.getByRole('button', { name: 'Save' }).click();
+ await expect(page.getByText('New bio text')).toBeVisible();
+});
+```
+
+Với Playwright Utils, TEA cũng có thể gợi ý pattern dùng `apiRequest` và `authToken`.
+
+### 9. Sau Phase 1 nên làm gì
+
+Thông thường:
+
+1. Sửa critical gap
+2. Chạy `test-review` để đảm bảo chất lượng
+3. Chạy Phase 2 để ra gate decision
+
+---
+
+## Phase 2: Quality Gate Decision
+
+Sau khi Phase 1 hoàn tất, chạy lại `trace` cho Phase 2.
+
+**Điều kiện tiên quyết:**
+
+- Có `traceability-matrix.md`
+- Có kết quả chạy test thực tế
+
+**Lưu ý:** Nếu không có test execution result, Phase 2 sẽ bị bỏ qua. Gate decision cần bằng chứng chạy test thật.
+
+### 10. Chạy lại `trace`
+
+```text
+trace
+```
+
+Chọn:
+
+```text
+Phase 2: Quality Gate Decision
+```
+
+### 11. Cung cấp thêm ngữ cảnh
+
+TEA sẽ hỏi:
+
+**Gate Type**
+
+- Story gate
+- Epic gate
+- Release gate
+- Hotfix gate
+
+**Decision Mode**
+
+- **Deterministic** - theo rule và threshold
+- **Manual** - team quyết định với hướng dẫn từ TEA
+
+**Ví dụ:**
+
+```text
+Gate type: Epic gate
+Decision mode: Deterministic
+```
+
+### 12. Cung cấp supporting evidence
+
+TEA thường sẽ yêu cầu:
+
+```text
+traceability-matrix.md
+test-review.md
+nfr-assessment.md
+test execution results
+```
+
+### 13. Review gate decision
+
+TEA sẽ ghi ra file riêng như:
+
+`gate-decision-{gate_type}-{story_id}.md`
+
+#### Ví dụ gate decision
+
+```markdown
+# Phase 2: Quality Gate Decision
+
+**Gate Type:** Epic Gate
+**Decision:** PASS ✅
+**Date:** 2026-01-13
+
+## Decision Summary
+
+**Verdict:** Ready to release
+
+**Evidence:**
+
+- P0 coverage: 100%
+- P1 coverage: 100%
+- Test quality score: 84/100
+- NFR assessment: PASS
+```
+
+#### Ví dụ coverage analysis trong gate
+
+| Priority | Required Coverage | Actual Coverage | Status |
+| -------- | ----------------- | --------------- | ---------------------- |
+| **P0** | 100% | 100% | ✅ PASS |
+| **P1** | 90% | 100% | ✅ PASS |
+| **P2** | 50% | 33% | ⚠️ Below (acceptable) |
+| **P3** | 20% | 0% | ✅ PASS (low priority) |
+
+#### Ví dụ quality metrics
+
+| Metric | Threshold | Actual | Status |
+| ------------------ | ---------------- | ----------- | ------ |
+| P0/P1 Coverage | P0=100%, P1>=90% | 100% / 100% | ✅ |
+| Test Quality Score | >80 | 84 | ✅ |
+| NFR Status | PASS | PASS | ✅ |
+
+### 14. Rule ra quyết định
+
+Khi `decision_mode = "deterministic"`, TEA dùng các rule sau:
+
+| P0 Coverage | P1 Coverage | Overall Coverage | Decision |
+| ----------- | ----------- | ---------------- | ----------------------------- |
+| 100% | ≥90% | ≥80% | **PASS** ✅ |
+| 100% | 80-89% | ≥80% | **CONCERNS** ⚠️ |
+| <100% | Any | Any | **FAIL** ❌ |
+| Any | <80% | Any | **FAIL** ❌ |
+| Any | Any | <80% | **FAIL** ❌ |
+| Any | Any | Any | **WAIVED** ⏭️ (with approval) |
+
+**Chi tiết:**
+
+- **PASS**: P0=100%, P1≥90%, overall≥80%
+- **CONCERNS**: P0=100%, P1 80-89%, overall≥80%
+- **FAIL**: P0<100% hoặc P1<80% hoặc overall<80%
+
+### 15. Ví dụ `CONCERNS`
+
+```markdown
+**Verdict:** CONCERNS ⚠️ - Proceed with monitoring
+
+**Evidence:**
+
+- P0 coverage: 100%
+- P1 coverage: 85%
+- Test quality: 78/100
+
+**Mitigation:**
+
+- 1 P1 requirement deferred
+- Monitoring alerts configured
+```
+
+### 16. Ví dụ `FAIL`
+
+```markdown
+**Verdict:** FAIL ❌ - Cannot release
+
+**Evidence:**
+
+- P0 coverage: 60%
+- Critical security vulnerability
+- Test quality: 55/100
+
+**Actions Required:**
+
+1. Add missing login tests
+2. Fix SQL injection
+3. Re-run security scan
+4. Re-run trace
+```
+
+## Bạn sẽ nhận được gì
+
+### Phase 1
+
+- Requirement-to-test mapping
+- Coverage classification: FULL / PARTIAL / NONE
+- Gap identification
+- Recommendation có thể hành động
+
+### Phase 2
+
+- Go/no-go verdict
+- Evidence summary
+- Approval hoặc waiver context
+- Next steps và monitoring plan
+
+## Pattern sử dụng theo loại dự án
+
+### Greenfield
+
+**Phase 3**
+
+```text
+After architecture complete:
+1. Run test-design
+2. Run trace Phase 1
+3. Use for implementation-readiness gate
+```
+
+**Phase 4**
+
+```text
+After each epic/story:
+1. Run trace Phase 1
+2. Identify gaps
+3. Add missing tests
+```
+
+**Release Gate**
+
+```text
+1. Run trace Phase 1
+2. Run trace Phase 2
+3. Get approvals
+4. Deploy if PASS or WAIVED
+```
+
+### Brownfield
+
+**Trước khi plan công việc mới:**
+
+```text
+1. Run trace Phase 1
+2. Establish baseline
+3. Understand existing coverage
+```
+
+**Trước release:**
+
+```text
+1. Run trace Phase 1
+2. Run trace Phase 2
+3. Compare with baseline
+```
+
+## Mẹo sử dụng
+
+### Chạy Phase 1 thường xuyên
+
+Đừng đợi tới release mới trace:
+
+```text
+After Story 1: trace Phase 1
+After Story 2: trace Phase 1
+Before Release: trace Phase 1 + Phase 2
+```
+
+### Đặt mục tiêu coverage theo priority
+
+- **P0:** 100%
+- **P1:** 90%
+- **P2:** 50%
+- **P3:** 20%
+
+### Dùng FULL / PARTIAL / NONE một cách chiến lược
+
+- **FULL**: item được test đầy đủ
+- **PARTIAL**: mới test một phần
+- **NONE**: chưa có test
+
+### Tự động hóa gate trong CI
+
+Ví dụ:
+
+```yaml
+- name: Check coverage
+ run: |
+ if [ $P0_COVERAGE -lt 100 ]; then exit 1; fi
+ if [ $P1_COVERAGE -lt 80 ]; then exit 1; fi
+ if [ $OVERALL_COVERAGE -lt 80 ]; then exit 1; fi
+```
+
+### Ghi waiver rõ ràng
+
+Nếu phải dùng `WAIVED`, cần ghi:
+
+- Ai phê duyệt
+- Lý do business
+- Điều kiện đi kèm
+- Rủi ro chấp nhận
+- Kế hoạch xử lý sau đó
+
+## Vấn đề thường gặp
+
+### Có quá nhiều gap
+
+Đừng sửa tất cả cùng lúc:
+
+1. Sửa P0 trước
+2. Sửa P1 rủi ro cao
+3. P2/P3 có thể defer
+
+### Không map được test với requirement
+
+Giải pháp:
+
+- Thêm comment traceability trong test
+- Hoặc thêm mã requirement vào tên test
+
+Ví dụ:
+
+```typescript
+test('[REQ-1] should display profile', async ({ page }) => {
+ // ...
+});
+```
+
+### Khó phân biệt FULL và PARTIAL
+
+**FULL:** tất cả acceptance criteria của item đều được test
+**PARTIAL:** mới bao phủ một phần acceptance criteria
+
+### Không rõ nên chọn PASS hay CONCERNS
+
+**Dùng PASS khi:**
+
+- P0 đạt 100%
+- P1 >90%
+- Không có issue nghiêm trọng
+
+**Dùng CONCERNS khi:**
+
+- P1 ở mức 80-89%
+- Có issue nhỏ nhưng có mitigation
+
+**Dùng FAIL khi:**
+
+- P0 <100%
+- P1 <80%
+- Có blocker bảo mật hoặc hiệu năng nghiêm trọng
+
+## Tài liệu liên quan
+
+- [How to Run Test Design](/vi-vn/how-to/workflows/run-test-design.md)
+- [How to Run Test Review](/vi-vn/how-to/workflows/run-test-review.md)
+- [How to Run NFR Assessment](/vi-vn/how-to/workflows/run-nfr-assess.md)
+
+## Hiểu thêm về khái niệm
+
+- [Risk-Based Testing](/vi-vn/explanation/risk-based-testing.md)
+- [TEA Overview](/vi-vn/explanation/tea-overview.md)
+
+## Tham chiếu
+
+- [Command: \*trace](/vi-vn/reference/commands.md#trace)
+- [TEA Configuration](/vi-vn/reference/configuration.md)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/workflows/setup-ci.md b/docs/vi-vn/how-to/workflows/setup-ci.md
new file mode 100644
index 0000000..ca53ff0
--- /dev/null
+++ b/docs/vi-vn/how-to/workflows/setup-ci.md
@@ -0,0 +1,740 @@
+---
+title: 'Cách thiết lập pipeline CI với TEA'
+description: Cấu hình chạy test tự động với selective testing và burn-in loop bằng TEA
+---
+
+# Cách thiết lập pipeline CI với TEA
+
+Sử dụng workflow `ci` của TEA để scaffold cấu hình CI/CD sẵn sàng cho production, phục vụ chạy test tự động với selective testing, sharding song song và phát hiện flaky test.
+
+## Khi nào nên dùng
+
+- Cần tự động hóa việc chạy test trong CI/CD
+- Muốn selective testing, chỉ chạy các test bị ảnh hưởng
+- Cần chạy song song để rút ngắn thời gian phản hồi
+- Muốn dùng burn-in loop để phát hiện flaky test
+- Đang thiết lập pipeline CI/CD mới
+- Đang tối ưu workflow CI/CD hiện có
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method
+- Có sẵn agent TEA
+- Đã cấu hình test framework, nên chạy `framework` trước
+- Đã có test để đưa vào CI
+- Có quyền truy cập nền tảng CI/CD như GitHub Actions, GitLab CI, v.v.
+
+## Các bước thực hiện
+
+### 1. Nạp TEA agent
+
+Bắt đầu một cuộc chat mới và nạp TEA:
+
+```text
+tea
+```
+
+### 2. Chạy workflow CI
+
+```text
+ci
+```
+
+### 3. Chọn nền tảng CI/CD
+
+TEA sẽ hỏi bạn đang dùng nền tảng nào.
+
+**Các nền tảng được hỗ trợ:**
+
+- **GitHub Actions** - phổ biến nhất
+- **GitLab CI**
+- **Jenkins** - sinh `Jenkinsfile` có stage song song, lưu artifact và xử lý sau lỗi
+- **Azure DevOps** - sinh `azure-pipelines.yml` với matrix strategy cho sharding và cache đặc thù Azure
+- **Harness** - sinh `.harness/pipeline.yaml` với execution dựa trên Kubernetes và các bước song song
+- **Circle CI**
+- **Other** - TEA cung cấp template tổng quát
+
+**Ví dụ:**
+
+```text
+GitHub Actions
+```
+
+### 4. Cấu hình chiến lược chạy test
+
+TEA sẽ hỏi về chiến lược thực thi test của bạn.
+
+#### Cấu trúc repository
+
+**Câu hỏi:** "What's your repository structure?"
+
+**Các lựa chọn:**
+
+- **Single app** - một ứng dụng ở thư mục gốc
+- **Monorepo** - nhiều app hoặc package
+- **Monorepo with affected detection** - chỉ test các package thay đổi
+
+**Ví dụ:**
+
+```text
+Monorepo with multiple apps
+Need selective testing for changed packages only
+```
+
+#### Chạy song song
+
+**Câu hỏi:** "Want to shard tests for parallel execution?"
+
+**Các lựa chọn:**
+
+- **No sharding** - chạy tuần tự
+- **Shard by workers** - chia qua N worker
+- **Shard by file** - mỗi file chạy độc lập song song
+
+**Ví dụ:**
+
+```text
+Yes, shard across 4 workers for faster execution
+```
+
+**Vì sao nên shard?**
+
+- **4 workers:** suite 20 phút có thể giảm còn khoảng 5 phút
+- **Dùng tài nguyên tốt hơn:** tận dụng runner hiệu quả
+- **Phản hồi nhanh hơn:** developer phải chờ ít hơn
+
+#### Burn-in loops
+
+**Câu hỏi:** "Want burn-in loops for flakiness detection?"
+
+**Các lựa chọn:**
+
+- **No burn-in** - chỉ chạy một lần
+- **PR burn-in** - chạy lặp nhiều lần trên pull request
+- **Nightly burn-in** - có job riêng để phát hiện flaky test
+
+**Ví dụ:**
+
+```text
+Yes, run tests 5 times on PRs to catch flaky tests early
+```
+
+**Vì sao nên burn-in?**
+
+- Bắt flaky test trước khi merge
+- Giảm lỗi CI ngắt quãng
+- Tăng độ tin cậy của test suite
+
+### 5. Rà soát cấu hình CI được sinh ra
+
+TEA sẽ tạo file workflow theo từng nền tảng.
+
+#### GitHub Actions (`.github/workflows/test.yml`)
+
+```yaml
+name: Test Suite
+
+on:
+ pull_request:
+ push:
+ branches: [main, develop]
+ schedule:
+ - cron: '0 2 * * *' # Nightly at 2 AM
+
+jobs:
+ test:
+ name: Test (Shard ${{ matrix.shard }})
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+
+ strategy:
+ fail-fast: false
+ matrix:
+ shard: [1, 2, 3, 4]
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: '.nvmrc'
+ cache: 'npm'
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Install Playwright browsers
+ run: npx playwright install --with-deps
+
+ - name: Run tests
+ run: npx playwright test --shard=${{ matrix.shard }}/4
+
+ - name: Upload test results
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: test-results-${{ matrix.shard }}
+ path: test-results/
+ retention-days: 7
+
+ - name: Upload test report
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: playwright-report-${{ matrix.shard }}
+ path: playwright-report/
+ retention-days: 7
+
+ burn-in:
+ name: Burn-In (Flakiness Detection)
+ runs-on: ubuntu-latest
+ if: github.event_name == 'pull_request'
+ timeout-minutes: 30
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: '.nvmrc'
+ cache: 'npm'
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Install Playwright browsers
+ run: npx playwright install --with-deps
+
+ - name: Run burn-in loop
+ run: |
+ for i in {1..5}; do
+ echo "=== Burn-in iteration $i/5 ==="
+ npx playwright test --grep-invert "@skip" || exit 1
+ done
+
+ - name: Upload burn-in results
+ if: failure()
+ uses: actions/upload-artifact@v4
+ with:
+ name: burn-in-failures
+ path: test-results/
+
+ selective:
+ name: Selective Tests
+ runs-on: ubuntu-latest
+ if: github.event_name == 'pull_request'
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: '.nvmrc'
+ cache: 'npm'
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Install Playwright browsers
+ run: npx playwright install --with-deps
+
+ - name: Run selective tests
+ run: npm run test:changed
+```
+
+#### GitLab CI (`.gitlab-ci.yml`)
+
+```yaml
+variables:
+ NODE_VERSION: '18'
+
+stages:
+ - test
+ - burn-in
+
+test:
+ stage: test
+ image: node:$NODE_VERSION
+ parallel: 4
+ script:
+ - npm ci
+ - npx playwright install --with-deps
+ - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
+ artifacts:
+ when: always
+ paths:
+ - test-results/
+ - playwright-report/
+ expire_in: 7 days
+ rules:
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+burn-in:
+ stage: burn-in
+ image: node:$NODE_VERSION
+ script:
+ - npm ci
+ - npx playwright install --with-deps
+ - |
+ for i in {1..5}; do
+ echo "=== Burn-in iteration $i/5 ==="
+ npx playwright test || exit 1
+ done
+ artifacts:
+ when: on_failure
+ paths:
+ - test-results/
+ rules:
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+```
+
+#### Burn-in testing
+
+**Lựa chọn 1: Burn-in cổ điển, dùng sẵn của Playwright**
+
+```json
+{
+ "scripts": {
+ "test": "playwright test",
+ "test:burn-in": "playwright test --repeat-each=5 --retries=0"
+ }
+}
+```
+
+**Cách hoạt động:**
+
+- Chạy mọi test 5 lần
+- Fail nếu có bất kỳ vòng lặp nào fail
+- Phát hiện flakiness trước khi merge
+
+**Nên dùng khi:** suite còn nhỏ, muốn lặp lại toàn bộ
+
+---
+
+**Lựa chọn 2: Burn-in thông minh, dùng Playwright Utils**
+
+Nếu `tea_use_playwright_utils: true`:
+
+**`scripts/burn-in-changed.ts`:**
+
+```typescript
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+await runBurnIn({
+ configPath: 'playwright.burn-in.config.ts',
+ baseBranch: 'main',
+});
+```
+
+**`playwright.burn-in.config.ts`:**
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+ skipBurnInPatterns: ['**/config/**', '**/*.md', '**/*types*'],
+ burnInTestPercentage: 0.3,
+ burnIn: { repeatEach: 5, retries: 0 },
+};
+
+export default config;
+```
+
+**`package.json`:**
+
+```json
+{
+ "scripts": {
+ "test:burn-in": "tsx scripts/burn-in-changed.ts"
+ }
+}
+```
+
+**Cách hoạt động:**
+
+- Phân tích `git diff`, chỉ lấy test bị ảnh hưởng
+- Lọc thông minh, bỏ qua config, docs, types
+- Giới hạn khối lượng chạy, ví dụ 30% số test bị ảnh hưởng
+- Mỗi test vẫn chạy 5 lần
+
+**Nên dùng khi:** suite lớn, muốn chọn lọc thông minh hơn
+
+---
+
+**So sánh:**
+
+| Tính năng | Burn-In cổ điển | Burn-In thông minh (PW-Utils) |
+| --------------- | ------------------------------------- | -------------------------------------- |
+| Thay đổi 1 file | Chạy toàn bộ 500 test x 5 = 2500 lượt | Chạy 3 test bị ảnh hưởng x 5 = 15 lượt |
+| Thay đổi config | Chạy toàn bộ | Bỏ qua, không có test bị ảnh hưởng |
+| Thay đổi type | Chạy toàn bộ | Bỏ qua, không ảnh hưởng runtime |
+| Thiết lập | Gần như không cần config | Cần thêm file config |
+
+**Khuyến nghị:** bắt đầu với cách cổ điển cho đơn giản, sau đó nâng sang Smart Burn-In khi suite tăng trưởng.
+
+### 6. Cấu hình secrets
+
+TEA sẽ cung cấp checklist secrets.
+
+**Secrets bắt buộc** cần thêm vào nền tảng CI/CD:
+
+```markdown
+## GitHub Actions Secrets
+
+Repository Settings → Secrets and variables → Actions
+
+### Required
+
+- None (tests run without external auth)
+
+### Optional
+
+- `TEST_USER_EMAIL` - thông tin đăng nhập user test
+- `TEST_USER_PASSWORD` - mật khẩu user test
+- `API_BASE_URL` - endpoint API cho test
+- `DATABASE_URL` - database test nếu cần
+```
+
+**Cách thêm secrets:**
+
+**GitHub Actions:**
+
+1. Vào `Settings → Secrets → Actions`
+2. Chọn `New repository secret`
+3. Thêm tên và giá trị
+4. Dùng trong workflow: `${{ secrets.TEST_USER_EMAIL }}`
+
+**GitLab CI:**
+
+1. Vào `Project Settings → CI/CD → Variables`
+2. Thêm tên biến và giá trị
+3. Dùng trong workflow: `$TEST_USER_EMAIL`
+
+### 7. Kiểm tra pipeline CI
+
+#### Push và xác minh
+
+**Commit file workflow:**
+
+```bash
+git add .github/workflows/test.yml
+git commit -m "ci: add automated test pipeline"
+git push
+```
+
+**Quan sát lượt chạy CI:**
+
+- GitHub Actions: tab `Actions`
+- GitLab CI: `CI/CD → Pipelines`
+- Circle CI: `Pipelines`
+
+**Kết quả mong đợi:**
+
+```text
+✓ test (shard 1/4) - 3m 24s
+✓ test (shard 2/4) - 3m 18s
+✓ test (shard 3/4) - 3m 31s
+✓ test (shard 4/4) - 3m 15s
+✓ burn-in - 15m 42s
+```
+
+#### Kiểm tra bằng pull request
+
+**Tạo PR thử nghiệm:**
+
+```bash
+git checkout -b test-ci-setup
+echo "# Test" > test.md
+git add test.md
+git commit -m "test: verify CI setup"
+git push -u origin test-ci-setup
+```
+
+**Mở PR và xác minh:**
+
+- Test chạy tự động
+- Burn-in chạy nếu được cấu hình cho PR
+- Selective tests chạy nếu đã bật
+- Tất cả check pass
+
+## Bạn sẽ nhận được gì
+
+### Chạy test tự động
+
+- **Mỗi pull request** - bắt lỗi trước khi merge
+- **Mỗi lần push lên main** - bảo vệ production
+- **Nightly** - regression toàn diện
+
+### Chạy song song
+
+- **Phản hồi nhanh hơn nhiều** - shard qua nhiều worker
+- **Tận dụng runner tốt hơn** - tăng hiệu quả tài nguyên CI
+
+### Selective testing
+
+- **Chỉ chạy test bị ảnh hưởng** - chọn theo `git diff`
+- **PR feedback nhanh hơn** - không phải chạy toàn bộ suite mỗi lần
+
+### Phát hiện flakiness
+
+- **Burn-in loops** - chạy đi chạy lại nhiều lần
+- **Phát hiện sớm** - bắt flaky test ngay trên PR
+- **Tăng niềm tin** - xác nhận suite đáng tin cậy
+
+### Thu thập artifact
+
+- **Test results** - lưu giữ trong 7 ngày
+- **Screenshots** - thu thập khi test fail
+- **Videos** - bản ghi toàn bộ test
+- **Traces** - file trace của Playwright để debug
+
+## Mẹo thực hành
+
+### Bắt đầu đơn giản, rồi tăng dần
+
+**Tuần 1:** pipeline cơ bản
+
+```yaml
+- Run tests on PR
+- Single worker (no sharding)
+```
+
+**Tuần 2:** thêm chạy song song
+
+```yaml
+- Shard across 4 workers
+- Faster feedback
+```
+
+**Tuần 3:** thêm selective testing
+
+```yaml
+- Git diff-based selection
+- Skip unaffected tests
+```
+
+**Tuần 4:** thêm burn-in
+
+```yaml
+- Detect flaky tests
+- Run on PR and nightly
+```
+
+### Tối ưu cho tốc độ phản hồi
+
+**Mục tiêu:** phản hồi PR dưới 5 phút
+
+**Chiến lược:**
+
+- Shard test qua nhiều worker
+- Dùng selective testing, chỉ chạy 20% test bị ảnh hưởng thay vì 100%
+- Cache dependency với `actions/cache`, `cache: 'npm'`
+- Chạy smoke test trước, full suite sau
+
+**Ví dụ workflow nhanh:**
+
+```yaml
+jobs:
+ smoke:
+ run: npm run test:smoke
+
+ full:
+ needs: smoke
+ run: npm test
+```
+
+### Dùng tag cho test
+
+Gắn tag để phục vụ chạy chọn lọc:
+
+```typescript
+test('@critical should login', async ({ page }) => {});
+test('@smoke should load homepage', async ({ page }) => {});
+test('@slow should process large file', async ({ page }) => {});
+test('@local-only should use local service', async ({ page }) => {});
+```
+
+**Trong CI:**
+
+```bash
+# PR: chỉ chạy critical và smoke
+npx playwright test --grep "@critical|@smoke"
+
+# Nightly: chạy tất cả trừ local-only
+npx playwright test --grep-invert "@local-only"
+```
+
+### Theo dõi hiệu năng CI
+
+```markdown
+## CI Metrics
+
+| Metric | Target | Current | Status |
+| ---------------- | -------- | ------- | ------ |
+| PR feedback time | < 5 min | 3m 24s | ✅ |
+| Full suite time | < 15 min | 12m 18s | ✅ |
+| Flakiness rate | < 1% | 0.3% | ✅ |
+| CI cost/month | < $100 | $75 | ✅ |
+```
+
+### Xử lý flaky test
+
+Khi burn-in phát hiện flakiness:
+
+1. **Quarantine flaky test**
+
+```typescript
+test.skip('flaky test - investigating', async ({ page }) => {
+ // TODO: Fix flakiness
+});
+```
+
+2. **Điều tra bằng trace viewer**
+
+```bash
+npx playwright show-trace test-results/trace.zip
+```
+
+3. **Sửa nguyên nhân gốc**
+
+- Thêm network-first patterns
+- Loại bỏ hard wait
+- Sửa race condition
+
+4. **Xác minh lại**
+
+```bash
+npm run test:burn-in -- tests/flaky.spec.ts --repeat 20
+```
+
+### Bảo mật secrets
+
+**Không commit secrets vào source:**
+
+```yaml
+# ❌ Bad
+- run: API_KEY=sk-1234... npm test
+
+# ✅ Good
+- run: npm test
+ env:
+ API_KEY: ${{ secrets.API_KEY }}
+```
+
+**Dùng secret theo từng môi trường:**
+
+- `STAGING_API_URL`
+- `PROD_API_URL`
+- `TEST_API_URL`
+
+### Cache mạnh tay khi hợp lý
+
+```yaml
+- uses: actions/setup-node@v4
+ with:
+ cache: 'npm'
+
+- name: Cache Playwright browsers
+ uses: actions/cache@v4
+ with:
+ path: ~/.cache/ms-playwright
+ key: playwright-${{ hashFiles('package-lock.json') }}
+```
+
+## Sự cố thường gặp
+
+### Test pass local nhưng fail trong CI
+
+**Triệu chứng:**
+
+- Local xanh nhưng CI đỏ
+- "Works on my machine"
+
+**Nguyên nhân phổ biến:**
+
+- Khác phiên bản Node
+- Khác phiên bản browser
+- Thiếu biến môi trường
+- Khác múi giờ
+- Race condition, CI chậm hơn local
+
+**Cách xử lý:**
+
+```yaml
+- uses: actions/setup-node@v4
+ with:
+ node-version-file: '.nvmrc'
+
+- run: npx playwright install --with-deps chromium@1.40.0
+
+ env:
+ TZ: 'America/New_York'
+```
+
+### CI chạy quá lâu
+
+**Vấn đề:** CI mất hơn 30 phút, developer chờ quá lâu.
+
+**Cách xử lý:**
+
+1. Shard test
+2. Dùng selective testing cho PR
+3. Chạy smoke trước, full suite sau
+4. Cache dependencies
+5. Tối ưu test, bỏ hard wait và giảm test chậm
+
+### Burn-in lúc nào cũng fail
+
+**Vấn đề:** job burn-in lần nào cũng fail.
+
+**Nguyên nhân:** suite đang flaky.
+
+**Cách xử lý:**
+
+1. Xác định test nào flaky
+2. Sửa bằng `test-review`
+3. Chạy burn-in riêng trên file nghi vấn:
+
+```bash
+npm run test:burn-in tests/flaky.spec.ts
+```
+
+### Hết quota CI minutes
+
+**Vấn đề:** tốn quá nhiều CI minutes, chạm giới hạn gói.
+
+**Cách xử lý:**
+
+1. Chỉ chạy full suite trên nhánh chính
+2. Dùng selective testing cho PR
+3. Chạy suite đắt đỏ vào nightly
+4. Dùng self-hosted runner nếu phù hợp
+
+## Tài liệu liên quan
+
+- [Cách thiết lập test framework](/docs/vi-vn/how-to/workflows/setup-test-framework.md) - nên làm trước
+- [Cách chạy test-review](/docs/vi-vn/how-to/workflows/run-test-review.md) - audit test trong CI
+- [Tích hợp Playwright Utils](/docs/vi-vn/how-to/customization/integrate-playwright-utils.md) - công cụ burn-in và tiện ích hỗ trợ
+
+## Hiểu thêm về khái niệm
+
+- [Tiêu chuẩn chất lượng test](/docs/vi-vn/explanation/test-quality-standards.md) - vì sao determinism quan trọng
+- [Network-first patterns](/docs/vi-vn/explanation/network-first-patterns.md) - tránh flaky trong CI
+
+## Tham chiếu
+
+- [Lệnh `*ci`](/docs/vi-vn/reference/commands.md#ci) - tham chiếu đầy đủ về command
+- [Cấu hình TEA](/docs/vi-vn/reference/configuration.md) - các option liên quan tới CI
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/workflows/setup-test-framework.md b/docs/vi-vn/how-to/workflows/setup-test-framework.md
new file mode 100644
index 0000000..c7d33a3
--- /dev/null
+++ b/docs/vi-vn/how-to/workflows/setup-test-framework.md
@@ -0,0 +1,142 @@
+---
+title: 'Cách thiết lập test framework với TEA'
+description: Cách dựng một test framework sẵn sàng cho production bằng TEA
+---
+
+Sử dụng workflow `framework` của TEA để scaffold một test framework sẵn sàng cho production cho dự án của bạn.
+
+## Khi nào nên dùng
+
+- Dự án chưa có test framework
+- Bộ test hiện tại chưa đủ production-ready
+- Dự án mới cần hạ tầng kiểm thử rõ ràng
+- Đang ở Phase 3 sau khi architecture cơ bản đã rõ
+
+:::note[Điều kiện tiên quyết]
+
+- Đã cài BMad Method
+- Architecture đã hoàn tất, hoặc ít nhất tech stack đã được chốt
+- Có TEA agent
+ :::
+
+## Các bước thực hiện
+
+### 1. Nạp TEA agent
+
+Bắt đầu một chat mới và nạp TEA.
+
+### 2. Chạy workflow framework
+
+```text
+framework
+```
+
+### 3. Trả lời các câu hỏi của TEA
+
+TEA sẽ hỏi về:
+
+- tech stack của bạn như React, Node, Python, Java, v.v.
+- test framework mong muốn:
+ - **Frontend/Fullstack:** Playwright, Cypress
+ - **Backend (Node.js):** Jest, Vitest hoặc Playwright cho API testing
+ - **Backend (Python):** pytest hoặc Playwright for Python
+ - **Backend (Java/Kotlin):** JUnit hoặc Playwright for Java
+ - **Backend (Go):** Go test
+ - **Backend (.NET):** dotnet test / xUnit hoặc Playwright for .NET
+ - **Backend (Ruby):** RSpec
+- phạm vi test như E2E, integration, unit, API
+- nền tảng CI/CD như GitHub Actions, GitLab CI, Jenkins, Azure DevOps, Harness
+
+### 4. Review output được sinh ra
+
+TEA thường tạo:
+
+- **Test scaffold** - cấu trúc thư mục và file config phù hợp ngôn ngữ
+- **Sample specs** - test mẫu theo best practice của framework đã chọn
+- **`.env.example`** - template biến môi trường
+- **Version file** - như `.nvmrc`, `.python-version`, `global.json`
+- **README updates** - tài liệu cách chạy test
+
+## Bạn sẽ nhận được gì
+
+**Frontend/Fullstack (Node.js):**
+
+```text
+tests/
+├── e2e/
+│ ├── example.spec.ts
+│ └── fixtures/
+├── integration/
+├── unit/
+├── playwright.config.ts
+└── README.md
+```
+
+**Backend (ví dụ Python):**
+
+```text
+tests/
+├── unit/
+│ └── test_example.py
+├── integration/
+├── api/
+├── conftest.py
+└── README.md
+```
+
+> **Lưu ý:** Playwright có binding chính thức cho Python, Java và .NET, nên không chỉ giới hạn ở Node.js.
+
+## Tùy chọn: tích hợp Playwright Utils
+
+TEA có thể tích hợp `@seontechnologies/playwright-utils` để cung cấp fixture nâng cao:
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+Bạn có thể bật trong lúc cài BMad hoặc đặt `tea_use_playwright_utils: true` trong config.
+
+**Một số utility có sẵn:** `api-request`, `network-recorder`, `auth-session`, `intercept-network-call`, `recurse`, `log`, `file-utils`, `burn-in`, `network-error-monitor`
+
+## Tùy chọn: MCP enhancements
+
+TEA có thể dùng Playwright MCP servers cho các capability mạnh hơn:
+
+- `playwright` - browser automation
+- `playwright-test` - test runner với failure analysis
+
+Cấu hình ở phần MCP settings của IDE hoặc môi trường bạn đang dùng.
+
+## Mẹo thực hành
+
+- **Thường chỉ chạy một lần mỗi repository**
+- **Nên chạy sau khi architecture rõ**
+- **Nên nối tiếp bằng `ci`** để đưa framework vào pipeline
+- Nếu là dự án lớn, nên rà sớm fixture strategy thay vì để về sau
+
+## Checklist cho QC
+
+- Có tách test theo tầng hoặc theo loại rõ ràng không
+- Có fixture nền tảng cho auth, seed dữ liệu, API client hay không
+- Có convention rõ cho tên file và cấu trúc thư mục không
+- Có cấu hình môi trường test rõ ràng không
+- Có sample test đủ làm chuẩn cho các file về sau không
+
+## Bước tiếp theo
+
+Sau khi thiết lập xong test framework:
+
+1. **Test Design** - tạo test plan cho hệ thống hoặc từng epic
+2. **CI Configuration** - cấu hình chạy test tự động
+3. **Story Implementation** - lúc này hạ tầng test đã sẵn sàng để DEV/QC dùng
+
+## Tài liệu liên quan
+
+- [Setup CI Pipeline](/docs/vi-vn/how-to/workflows/setup-ci.md)
+- [Run Test Design](/docs/vi-vn/how-to/workflows/run-test-design.md)
+- [Integrate Playwright Utils](/docs/vi-vn/how-to/customization/integrate-playwright-utils.md)
+- [TEA Overview](/docs/vi-vn/explanation/tea-overview.md)
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/how-to/workflows/teach-me-testing.md b/docs/vi-vn/how-to/workflows/teach-me-testing.md
new file mode 100644
index 0000000..bcddd93
--- /dev/null
+++ b/docs/vi-vn/how-to/workflows/teach-me-testing.md
@@ -0,0 +1,217 @@
+---
+title: 'Cách học kiểm thử với TEA Academy'
+description: Trợ lý học tập nhiều buổi, dạy kiểm thử từ cơ bản đến nâng cao và có lưu trạng thái
+---
+
+# Cách học kiểm thử với TEA Academy
+
+Dùng workflow `teach-me-testing` của TEA để học kiểm thử theo tiến trình qua 7 buổi có cấu trúc. Workflow này được thiết kế cho việc tự học trong 1-2 tuần với khả năng tự động theo dõi tiến độ.
+
+## Khi nào nên dùng
+
+- **QA mới:** onboarding đầy đủ về các nền tảng kiểm thử
+- **Developer:** học testing theo góc nhìn tích hợp
+- **Team lead:** hiểu pattern kiến trúc và thực hành của đội
+- **VP/Manager:** nắm chiến lược kiểm thử và quality metrics
+- **Bất kỳ ai:** muốn học testing mà không cần instructor đi kèm
+
+**Rất phù hợp cho:**
+
+- Onboarding trong công ty
+- Tự học với khả năng pause và resume bất cứ lúc nào
+- Khám phá không tuyến tính theo mức kinh nghiệm
+- Xây nền tảng testing có thể mở rộng lâu dài
+
+## Bạn sẽ học được gì
+
+### 7 buổi học tăng tiến
+
+1. **Khởi động nhanh (30 phút)** - giới thiệu TEA Lite, hiểu engagement models
+2. **Khái niệm cốt lõi (45 phút)** - risk-based testing (P0-P3), Definition of Done
+3. **Kiến trúc & patterns (60 phút)** - fixtures, network-first patterns, data factories
+4. **Test Design (60 phút)** - workflow đánh giá rủi ro và lập kế hoạch coverage
+5. **ATDD & Automate (60 phút)** - cách tiếp cận TDD red-green, test generation
+6. **Quality & Trace (45 phút)** - test review, coverage traceability
+7. **Pattern nâng cao (liên tục)** - khám phá 42 knowledge fragments theo nhu cầu
+
+### Giá trị bạn nhận được
+
+- Nền tảng testing quan trọng như risk-based testing, test pyramid và các loại test
+- Hiểu phương pháp TEA với 9 workflow và các pattern kiến trúc
+- Kỹ năng thực hành để viết test tốt đầu tiên của bạn
+- Artifact học tập như session notes và completion certificate
+- Sự tự tin để áp dụng TEA vào dự án thực tế
+
+## Điều kiện tiên quyết
+
+- Đã cài BMad Method với module TEA
+- Có quyền truy cập tài liệu và knowledge base của TEA
+- Mỗi buổi có 30-90 phút học tập, có thể pause và resume
+- Sẵn sàng học tăng tiến trong 1-2 tuần
+
+## Cách hoạt động
+
+### Bắt đầu từ đầu
+
+Mở một chat mới và nạp TEA:
+
+```text
+tea
+```
+
+Sau đó chọn Teach Me Testing:
+
+```text
+TMT
+```
+
+Hoặc gọi trực tiếp:
+
+```text
+teach-me-testing
+```
+
+### Đánh giá ban đầu
+
+Workflow sẽ hỏi:
+
+- **Vai trò của bạn:** QA, Dev, Lead hoặc VP để tùy biến ví dụ
+- **Mức kinh nghiệm:** beginner, intermediate hoặc experienced
+- **Mục tiêu học tập:** bạn muốn đạt được điều gì
+- **Pain points:** thách thức testing hiện tại, nếu có
+
+### Session menu
+
+Sau phần đánh giá, bạn sẽ thấy menu của cả 7 session cùng với:
+
+- Buổi đã hoàn thành kèm điểm số
+- Buổi đang học
+- Buổi chưa bắt đầu
+- Tỷ lệ hoàn thành
+- Buổi được đề xuất tiếp theo
+
+**Bạn có thể nhảy tới bất kỳ session nào** chứ không bị khóa theo đường tuyến tính.
+
+### Luồng của mỗi buổi
+
+1. **Teaching** - trình bày khái niệm kèm ví dụ phù hợp vai trò
+2. **Quiz** - 3 câu hỏi để kiểm tra hiểu bài, cần **>= 70%** để vượt qua
+3. **Session Notes** - sinh artifact ghi lại ý chính
+4. **Progress Update** - tự động lưu, có thể dừng ở bất kỳ lúc nào
+5. **Return to Menu** - chọn session tiếp theo hoặc thoát
+
+## Theo dõi tiến độ
+
+Tiến độ của bạn được lưu tự động:
+
+- Progress file: `{test_artifacts}/teaching-progress/{your-name}-tea-progress.yaml`
+- Session notes: `{test_artifacts}/tea-academy/{your-name}/session-{N}-notes.md`
+- Certificate: `{test_artifacts}/tea-academy/{your-name}/tea-completion-certificate.md` sau khi xong cả 7 buổi
+
+### Tiếp tục sau
+
+Chỉ cần chạy lại workflow. TEA sẽ tự phát hiện tiến độ cũ và hiển thị đúng điểm bạn đang dở.
+
+## Lộ trình học theo kinh nghiệm
+
+### Người mới
+
+**Lộ trình đề xuất:** Buổi 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7
+
+Bắt đầu từ Buổi 1 và đi tuần tự. Mỗi buổi xây trên nền của buổi trước.
+
+**Thời lượng:** 1-2 tuần, 30-90 phút mỗi buổi
+
+### Trung cấp
+
+**Lộ trình đề xuất:** Buổi 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7
+
+Bạn có thể đi nhanh qua Buổi 1-2 và tập trung hơn vào Buổi 3-6.
+
+**Thời lượng:** khoảng 1 tuần, có thể bỏ qua chủ đề đã quen
+
+### Người có kinh nghiệm
+
+**Lộ trình đề xuất:** vào thẳng Buổi 3, 4, 7
+
+Bỏ qua phần nhập môn và tập trung vào:
+
+- Buổi 3: pattern kiến trúc của TEA
+- Buổi 4: workflow Test Design
+- Buổi 7: pattern nâng cao qua 42 knowledge fragments
+
+**Thời lượng:** khoảng 3-4 giờ, rất tập trung
+
+## Nội dung từng buổi
+
+### Buổi 1: Khởi động nhanh
+
+- TEA là gì và vì sao nó tồn tại
+- Cách tiếp cận TEA Lite
+- Engagement models
+- Tổng quan workflow `automate`
+
+### Buổi 2: Khái niệm cốt lõi
+
+- Triết lý testing as engineering
+- Risk-based testing
+- Chấm điểm Probability × Impact
+- Definition of Done với 7 nguyên tắc chất lượng
+
+### Buổi 3: Kiến trúc & patterns
+
+- Fixture composition patterns
+- Network-first patterns để tránh race condition
+- Data factories
+- Step-file architecture
+
+### Buổi 4: Test Design
+
+- Workflow Test Design
+- Đánh giá risk/testability
+- Coverage planning ở các mức unit/integration/E2E
+- Test priorities matrix (mục tiêu coverage P0-P3)
+
+### Buổi 5: ATDD & Automate
+
+- Workflow ATDD với failing tests first
+- Vòng lặp TDD red-green-refactor
+- Workflow `automate` để mở rộng coverage
+- API testing patterns
+
+### Buổi 6: Quality & Trace
+
+- Workflow Test Review với các chiều chất lượng
+- Coverage traceability
+- Quality metrics có ý nghĩa
+- Release gate decisions
+
+### Buổi 7: Pattern nâng cao
+
+- Khám phá 42 knowledge fragments theo nhu cầu
+- Đào sâu các pattern phù hợp bối cảnh của bạn
+- Đối chiếu source trên GitHub khi cần
+
+## Chứng nhận hoàn thành
+
+Hoàn thành cả 7 buổi để nhận chứng nhận gồm:
+
+- Ngày hoàn thành và điểm từng buổi
+- Điểm trung bình
+- Danh sách kỹ năng đã đạt được
+- Đường dẫn tới các artifact học tập
+
+## Mẹo để học tốt
+
+1. Dành thời gian riêng cho từng buổi
+2. Ghi thêm note cá nhân song song với note tự động
+3. Áp dụng ngay vào dự án hiện tại
+4. Dùng Buổi 7 để đào sâu chủ đề đang cần gấp
+5. Chia sẻ lại với đồng đội
+
+## Tùy biến theo vai trò
+
+- **QA Engineers:** ưu tiên workflow, coverage, metrics
+- **Developers:** ưu tiên TDD, integration, API testing
+- **Tech Leads:** ưu tiên architecture, standard đội nhóm, review
+- **VPs/Managers:** ưu tiên strategy, ROI, scaling, quality metrics
diff --git a/docs/vi-vn/index.md b/docs/vi-vn/index.md
new file mode 100644
index 0000000..91889cf
--- /dev/null
+++ b/docs/vi-vn/index.md
@@ -0,0 +1,65 @@
+---
+title: Chào mừng
+description: Test Architect (TEA) - quy trình kiểm thử dựa trên rủi ro, hướng dẫn tự động hóa và cổng quyết định phát hành cho BMad Method
+---
+
+# Test Architect (TEA)
+
+## TEA là gì?
+
+TEA (Test Engineering Architect) là một module của BMAD dành cho chiến lược kiểm thử và tự động hóa. Bộ công cụ này cung cấp 9 workflow bao phủ các hoạt động học tập, thiết lập, thiết kế, tự động hóa, review và ra quyết định phát hành.
+
+- **Vận hành theo workflow**: Nhiều workflow phù hợp với công việc hằng ngày của Test Architect.
+- **Đầu ra nhất quán**: Hướng dẫn từ knowledge base giúp duy trì tiêu chuẩn thống nhất, bất kể bạn đang dùng agent nào.
+- **Dựa trên rủi ro**: Ưu tiên P0-P3 theo công thức xác suất × tác động.
+- **Cổng phát hành**: Quyết định go/no-go có thể truy vết và có bằng chứng hỗ trợ.
+
+## Cài đặt nhanh
+
+```bash
+npx bmad-method install
+# Chọn: Test Architect (TEA)
+```
+
+Sau đó kích hoạt workflow qua chat:
+
+```text
+bmad-tea # Nạp agent/menu TEA
+test-design # Chạy workflow Test Design
+```
+
+## Bắt đầu
+
+Chọn lộ trình phù hợp:
+
+- **Mới làm quen với kiểm thử?** Bắt đầu với [TEA Academy](/vi-vn/tutorials/learn-testing-tea-academy) - học kiểm thử từ nền tảng đến nâng cao (7 buổi, 1-2 tuần)
+- **TEA Lite**: Bắt đầu với [Test Automation](/vi-vn/how-to/workflows/run-automate) trong khoảng 30 phút
+- **Full TEA**: Đọc [TEA Overview](/vi-vn/explanation/tea-overview) để xem toàn bộ bản đồ workflow
+- **Enterprise**: Chọn [Greenfield](/vi-vn/how-to/brownfield/use-tea-for-enterprise) hoặc [Brownfield](/vi-vn/how-to/brownfield/use-tea-with-existing-tests)
+- **Mở rộng tùy chỉnh**: Xem [Extend TEA with Custom Workflows](/vi-vn/how-to/customization/extend-tea-with-custom-workflows)
+
+## Workflow cốt lõi
+
+| Workflow | Trigger | Mục đích |
+| --------------------------------------------------------------- | ------- | -------------------------------------------- |
+| [Teach Me Testing](/vi-vn/how-to/workflows/teach-me-testing) | TMT | Học kiểm thử qua 7 buổi |
+| [Framework Setup](/vi-vn/how-to/workflows/setup-test-framework) | TF | Khởi tạo test framework |
+| [CI/CD Integration](/vi-vn/how-to/workflows/setup-ci) | CI | Thiết lập pipeline chất lượng |
+| [Test Design](/vi-vn/how-to/workflows/run-test-design) | TD | Lập kế hoạch kiểm thử dựa trên rủi ro |
+| [ATDD](/vi-vn/how-to/workflows/run-atdd) | AT | Viết acceptance test thất bại trước theo TDD |
+| [Test Automation](/vi-vn/how-to/workflows/run-automate) | TA | Mở rộng độ bao phủ tự động hóa |
+| [Test Review](/vi-vn/how-to/workflows/run-test-review) | RV | Đánh giá chất lượng có chấm điểm |
+| [Requirements Tracing](/vi-vn/how-to/workflows/run-trace) | TR | Ánh xạ độ bao phủ và quyết định gate |
+| [NFR Assessment](/vi-vn/how-to/workflows/run-nfr-assess) | NR | Đánh giá yêu cầu phi chức năng |
+
+## Cấu trúc tài liệu
+
+- **[Tutorial](/vi-vn/tutorials/tea-lite-quickstart/)**: Học TEA theo từng bước
+- **[How-To Guides](/vi-vn/how-to/workflows/run-test-design)**: Hướng dẫn theo tác vụ
+- **[Explanation](/vi-vn/explanation/testing-as-engineering/)**: Giải thích khái niệm và kiến trúc
+- **[Reference](/vi-vn/reference/commands)**: Lệnh, cấu hình, knowledge base
+- **[Glossary](/vi-vn/glossary)**: Thuật ngữ và định nghĩa
+
+## Hỗ trợ
+
+- **Issues**: [GitHub Issues](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/issues)
diff --git a/docs/vi-vn/reference/commands.md b/docs/vi-vn/reference/commands.md
new file mode 100644
index 0000000..7e91629
--- /dev/null
+++ b/docs/vi-vn/reference/commands.md
@@ -0,0 +1,301 @@
+---
+title: 'Tham chiếu lệnh TEA'
+description: Bảng tham chiếu nhanh cho toàn bộ 9 workflow của TEA - đầu vào, đầu ra và liên kết tới hướng dẫn chi tiết
+---
+
+# Tham chiếu lệnh TEA
+
+Đây là bảng tham chiếu nhanh cho toàn bộ 9 workflow của TEA (Test Engineering Architect). Nếu cần hướng dẫn từng bước, hãy xem tài liệu how-to.
+
+Tất cả workflow liệt kê dưới đây hiện đều được hỗ trợ, bao gồm cả `nfr-assess`.
+
+**Cách gọi theo công cụ:**
+
+- **Claude Code / Cursor / Windsurf:** dùng slash command, ví dụ `/bmad:tea:automate`
+- **Codex:** dùng `$` skills trong `.agents/skills`, ví dụ `$bmad-tea-testarch-automate`
+- **TEA extension tùy biến:** đóng gói workflow thành custom content/module rồi gắn vào `bmad-tea` qua customization. Xem [Extend TEA with Custom Workflows](../how-to/customization/extend-tea-with-custom-workflows.md)
+
+## Mục lục nhanh
+
+- [`teach-me-testing`](#teach-me-testing) - Học kiểm thử với TEA Academy
+- [`framework`](#framework) - Scaffold test framework
+- [`ci`](#ci) - Thiết lập pipeline CI/CD
+- [`test-design`](#test-design) - Lập kế hoạch kiểm thử dựa trên rủi ro
+- [`atdd`](#atdd) - Acceptance TDD
+- [`automate`](#automate) - Test automation
+- [`test-review`](#test-review) - Audit chất lượng
+- [`nfr-assess`](#nfr-assess) - Đánh giá NFR
+- [`trace`](#trace) - Truy vết coverage
+
+---
+
+## teach-me-testing
+
+**Mục đích:** trợ lý học tập tương tác, dạy kiểm thử từ nền tảng đến thực hành nâng cao
+
+**Phase:** Learning / Onboarding (trước mọi phase khác)
+
+**Tần suất:** mỗi người học một lần, có thể quay lại bất kỳ session nào
+
+**Đầu vào chính:**
+
+- Vai trò (QA, Dev, Lead, VP)
+- Mức kinh nghiệm (beginner, intermediate, experienced)
+- Mục tiêu học tập
+
+**Đầu ra chính:**
+
+- File theo dõi tiến độ (`teaching-progress/{user}-tea-progress.yaml`)
+- Ghi chú cho từng session đã hoàn thành
+- Chứng nhận hoàn thành (sau cả 7 session)
+- Learning artifacts như note và ví dụ test
+
+**7 session chính:**
+
+1. Quick Start (30 phút) - giới thiệu TEA Lite và engagement models
+2. Core Concepts (45 phút) - risk-based testing, P0-P3, DoD
+3. Architecture (60 phút) - fixtures, network-first, data factories
+4. Test Design (60 phút) - risk assessment và coverage planning
+5. ATDD & Automate (60 phút) - TDD red-green và test generation
+6. Quality & Trace (45 phút) - test review, traceability, metrics
+7. Advanced Patterns (liên tục) - khám phá 42 knowledge fragments theo nhu cầu
+
+**Tính năng:**
+
+- Nhiều session với khả năng lưu trạng thái để pause/resume
+- Không tuyến tính hoàn toàn, có thể nhảy vào bất kỳ session nào theo kinh nghiệm
+- Quiz validation với ngưỡng đỗ **>= 70%**
+- Ví dụ điều chỉnh theo vai trò (QA/Dev/Lead/VP)
+- Tự động theo dõi tiến độ
+
+**How-To Guide:** [Learn Testing with TEA Academy](/docs/vi-vn/how-to/workflows/teach-me-testing.md)
+
+**Tutorial:** [Learn Testing with TEA Academy](/docs/vi-vn/tutorials/learn-testing-tea-academy.md)
+
+---
+
+## framework
+
+**Mục đích:** scaffold production-ready test framework (Playwright hoặc Cypress)
+
+**Phase:** Phase 3 (Solutioning)
+
+**Tần suất:** một lần mỗi dự án
+
+**Đầu vào chính:**
+
+- Tech stack, lựa chọn test framework, testing scope
+
+**Đầu ra chính:**
+
+- Thư mục `tests/` với `support/fixtures/` và `support/helpers/`
+- `playwright.config.ts` hoặc `cypress.config.ts`
+- `.env.example`, `.nvmrc`
+- Sample tests theo best practice
+
+**How-To Guide:** [Setup Test Framework](/docs/vi-vn/how-to/workflows/setup-test-framework.md)
+
+---
+
+## ci
+
+**Mục đích:** thiết lập pipeline CI/CD với selective testing và burn-in
+
+**Phase:** Phase 3 (Solutioning)
+
+**Tần suất:** một lần mỗi dự án
+
+**Đầu vào chính:**
+
+- Nền tảng CI (GitHub Actions, GitLab CI, v.v.)
+- Sharding strategy, burn-in preferences
+
+**Đầu ra chính:**
+
+- CI workflow theo nền tảng (`.github/workflows/test.yml`, v.v.)
+- Cấu hình chạy song song
+- Burn-in loops để phát hiện flaky test
+- Checklist secrets
+
+**How-To Guide:** [Setup CI Pipeline](/docs/vi-vn/how-to/workflows/setup-ci.md)
+
+---
+
+## test-design
+
+**Mục đích:** lập kế hoạch kiểm thử dựa trên rủi ro cùng coverage strategy
+
+**Phase:** Phase 3 (system-level), Phase 4 (epic-level)
+
+**Tần suất:** một lần ở mức hệ thống, sau đó theo từng epic
+
+**Chế độ:**
+
+- **System-level:** review testability ở mức kiến trúc, sinh **hai tài liệu**
+- **Epic-level:** risk assessment theo epic, sinh **một tài liệu**
+
+**Đầu vào chính:**
+
+- System-level: architecture, PRD, ADR
+- Epic-level: epic, stories, acceptance criteria
+
+**Đầu ra chính:**
+
+**System-Level (HAI tài liệu):**
+
+- `test-design-architecture.md` - cho team Architecture/Dev
+ - Quick Guide (`BLOCKERS` / `HIGH PRIORITY` / `INFO ONLY`)
+ - Risk assessment có chấm điểm
+ - Testability concerns và gaps
+ - Mitigation plans
+- `test-design-qa.md` - cho team QA
+ - Test execution recipe
+ - Coverage plan (P0/P1/P2/P3 có checkbox)
+ - Sprint 0 setup requirements
+ - NFR readiness summary
+
+**Epic-Level (MỘT tài liệu):**
+
+- `test-design-epic-N.md`
+ - Risk assessment (điểm probability × impact)
+ - Test priorities (P0-P3)
+ - Coverage strategy
+ - Mitigation plans
+
+**Vì sao system-level cần 2 tài liệu?**
+
+- Team architecture quét blocker trong <5 phút
+- Team QA có test recipe có thể hành động ngay
+- Giảm trùng lặp, ưu tiên cross-reference
+- Tách rõ điều cần giao và cách kiểm thử
+
+**Browser Automation (CLI/MCP):** exploratory mode để khám phá UI bằng browser thật
+
+**How-To Guide:** [Run Test Design](/docs/vi-vn/how-to/workflows/run-test-design.md)
+
+---
+
+## atdd
+
+**Mục đích:** tạo scaffold acceptance test ở red phase **trước** implementation (pha đỏ của TDD)
+
+**Phase:** Phase 4 (Implementation)
+
+**Tần suất:** theo từng story, tùy chọn
+
+**Đầu vào chính:**
+
+- Story có acceptance criteria, test design và test levels
+
+**Đầu ra chính:**
+
+- Red-phase test scaffolds trong `tests/api/`, `tests/e2e/` được đánh dấu bằng `test.skip()`
+- Implementation checklist gắn với `story_key`
+- Story metadata / handoff paths cho downstream `dev-story`
+
+**Browser Automation (CLI/MCP):** recording mode cho skeleton UI trong trường hợp hiếm
+
+**How-To Guide:** [Run ATDD](/docs/vi-vn/how-to/workflows/run-atdd.md)
+
+---
+
+## automate
+
+**Mục đích:** mở rộng test coverage sau khi implementation hoàn tất
+
+**Phase:** Phase 4 (Implementation)
+
+**Tần suất:** theo từng story/feature
+
+**Đầu vào chính:**
+
+- Mô tả feature, test design, test hiện có để tránh duplication
+
+**Đầu ra chính:**
+
+- Comprehensive test suite trong `tests/e2e/`, `tests/api/`
+- Fixture và README cập nhật
+- Definition of Done summary
+
+**Browser Automation (CLI/MCP):** healing + recording modes để sửa test và xác minh selector
+
+**How-To Guide:** [Run Automate](/docs/vi-vn/how-to/workflows/run-automate.md)
+
+---
+
+## test-review
+
+**Mục đích:** audit chất lượng test với thang điểm 0-100
+
+**Phase:** Phase 4 (tùy chọn theo story), Release Gate
+
+**Tần suất:** theo epic hoặc trước release
+
+**Đầu vào chính:**
+
+- Phạm vi review, có thể là file, thư mục hoặc cả suite
+
+**Đầu ra chính:**
+
+- `test-review.md` với quality score (0-100)
+- Các vấn đề nghiêm trọng kèm hướng sửa
+- Recommendations
+- Category scores theo từng chiều: Determinism, Isolation, Maintainability, Performance
+- Coverage guidance chỉ mang tính thông tin; coverage scoring và gate do `trace` xử lý
+
+**Nhóm điểm:**
+
+- Determinism: 30%
+- Isolation: 30%
+- Maintainability: 25%
+- Performance: 15%
+
+**How-To Guide:** [Run Test Review](/docs/vi-vn/how-to/workflows/run-test-review.md)
+
+---
+
+## nfr-assess
+
+**Mục đích:** xác thực yêu cầu phi chức năng bằng bằng chứng
+
+**Phase:** thường dùng ở planning sâu và Release Gate
+
+**Trọng tâm:** security, performance, reliability, maintainability và các NFR quan trọng khác
+
+**Đầu vào chính:**
+
+- PRD, architecture, bằng chứng hiện có, ràng buộc phi chức năng
+
+**Đầu ra chính:**
+
+- Báo cáo NFR
+- Rủi ro hoặc gap
+- Hành động ưu tiên cần xử lý
+
+**How-To Guide:** [Run NFR Assess](/docs/vi-vn/how-to/workflows/run-nfr-assess.md)
+
+---
+
+## trace
+
+**Mục đích:** truy vết coverage và đưa ra gate decision
+
+**Phase:** dùng trong lúc triển khai và đặc biệt quan trọng ở Release Gate
+
+**Hai phase:**
+
+- **Phase 1:** sinh coverage matrix, gap analysis và recommendation
+- **Phase 2:** đưa ra `PASS`, `CONCERNS`, `FAIL` hoặc `WAIVED`
+
+**Đầu vào chính:**
+
+- Requirements, spec, test design, hoặc source tree có thể phân tích
+- Test location và kết quả test execution (đặc biệt cho Phase 2)
+
+**Đầu ra chính:**
+
+- `traceability-matrix.md`
+- Danh sách coverage gaps theo mức ưu tiên
+- Gate decision có evidence
+
+**How-To Guide:** [Run Trace](/docs/vi-vn/how-to/workflows/run-trace.md)
diff --git a/docs/vi-vn/reference/configuration.md b/docs/vi-vn/reference/configuration.md
new file mode 100644
index 0000000..c7da362
--- /dev/null
+++ b/docs/vi-vn/reference/configuration.md
@@ -0,0 +1,1017 @@
+---
+title: 'Tham chiếu cấu hình TEA'
+description: Tài liệu tham chiếu đầy đủ cho các tùy chọn cấu hình và vị trí file cấu hình của TEA
+---
+
+# Tham chiếu cấu hình TEA
+
+Tài liệu tham chiếu đầy đủ cho toàn bộ tùy chọn cấu hình của TEA (Test Engineering Architect).
+
+## Vị trí các file cấu hình
+
+### Cấu hình người dùng (do installer tạo)
+
+**Vị trí:** `_bmad/tea/config.yaml`
+
+**Mục đích:** Lưu các giá trị cấu hình riêng cho repository của bạn
+
+**Được tạo bởi:** BMad installer
+
+**Trạng thái:** Thường được thêm vào `.gitignore` vì chứa giá trị riêng của từng người dùng
+
+**Cách dùng:** Chỉnh sửa file này để thay đổi hành vi của TEA trong dự án
+
+**Ví dụ:**
+
+```yaml
+# _bmad/tea/config.yaml
+project_name: my-awesome-app
+user_skill_level: intermediate
+output_folder: _bmad-output
+test_artifacts: _bmad-output/test-artifacts
+tea_use_playwright_utils: true
+tea_use_pactjs_utils: false
+tea_pact_mcp: 'none'
+tea_browser_automation: 'auto'
+tea_execution_mode: 'auto'
+tea_capability_probe: true
+```
+
+### Schema chuẩn (nguồn định nghĩa chính thức)
+
+**Vị trí:** `src/module.yaml`
+
+**Mục đích:** Định nghĩa các khóa cấu hình có sẵn, giá trị mặc định và câu hỏi mà installer sẽ hiển thị
+
+**Được tạo bởi:** Các maintainer của BMAD
+
+**Trạng thái:** Được quản lý phiên bản trong repository BMAD
+
+**Cách dùng:** Chỉ tham chiếu, không chỉnh sửa trừ khi bạn đang đóng góp trực tiếp vào BMAD
+
+**Lưu ý:** Installer sẽ đọc `module.yaml` để hỏi người dùng về các giá trị cấu hình, sau đó ghi lựa chọn vào `_bmad/tea/config.yaml` trong dự án của bạn.
+
+---
+
+## Các tùy chọn cấu hình của TEA
+
+### test_artifacts
+
+Thư mục đầu ra gốc dành cho các artifact do TEA tạo ra, ví dụ test design, report, traceability, v.v.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `string`
+
+**Mặc định:** `{output_folder}/test-artifacts`
+
+**Mục đích:** Cho phép artifact của TEA nằm ngoài thư mục output cốt lõi của BMM nếu cần.
+
+**Ví dụ:**
+
+```yaml
+test_artifacts: docs/testing-artifacts
+```
+
+### tea_use_playwright_utils
+
+Bật tích hợp Playwright Utils để dùng fixture và utility sẵn sàng cho production.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `boolean`
+
+**Mặc định:** `true`
+
+**Câu hỏi từ installer:**
+
+```text
+Enable Playwright Utils integration?
+```
+
+**Mục đích:** Cho phép TEA:
+
+- Đưa `playwright-utils` vào scaffold do `framework` tạo ra
+- Sinh test dùng fixture của `playwright-utils`
+- Review test theo các pattern của `playwright-utils`
+- Cấu hình CI với burn-in và selective testing utility
+
+**Ảnh hưởng tới workflow:**
+
+- `framework` - thêm import `playwright-utils` và ví dụ fixture
+- `atdd` - dùng các fixture như `apiRequest`, `authSession` trong test được tạo
+- `automate` - tận dụng utility cho pattern test
+- `test-review` - review test theo best practice của `playwright-utils`
+- `ci` - thêm burn-in utility và selective testing
+
+**Ví dụ (bật):**
+
+```yaml
+tea_use_playwright_utils: true
+```
+
+**Ví dụ (tắt):**
+
+```yaml
+tea_use_playwright_utils: false
+```
+
+**Điều kiện tiên quyết:**
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Liên quan:**
+
+- [Hướng dẫn tích hợp Playwright Utils](/vi-vn/how-to/customization/integrate-playwright-utils.md)
+- [Playwright Utils trên npm](https://www.npmjs.com/package/@seontechnologies/playwright-utils)
+
+---
+
+### tea_use_pactjs_utils
+
+Bật tích hợp Pact.js Utils để hỗ trợ consumer-driven contract testing ở mức sẵn sàng cho production.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `boolean`
+
+**Mặc định:** `false`
+
+**Câu hỏi từ installer:**
+
+```text
+Enable Pact.js Utils for consumer-driven contract testing?
+```
+
+**Mục đích:** Cho phép TEA:
+
+- Nạp các knowledge fragment của Pact.js Utils trong lúc load context
+- Tạo scaffold contract test và ví dụ trong `framework`
+- Sinh hướng dẫn contract testing trong `atdd` và `automate`
+- Review pattern provider verification trong `test-review`
+- Thêm stage contract pipeline và gate trong `ci`
+
+**Ảnh hưởng tới workflow:**
+
+- `framework` - tạo thư mục pact test và sample pattern của pactjs-utils
+- `atdd` - nạp fragment của pactjs-utils để hỗ trợ ngữ cảnh sinh test
+- `automate` - nạp fragment của pactjs-utils và truyền cấu hình pact cho subagent
+- `test-design` - nạp fragment của pactjs-utils cho planning mức hệ thống/epic
+- `test-review` - dùng pattern provider/review của pactjs-utils
+- `ci` - thêm stage contract-test và quality gate
+
+**Dùng khi nào:** Đội của bạn đã dùng consumer-driven contract testing hoặc muốn TEA chủ động scaffold pattern liên quan tới Pact. Nếu dự án không dùng Pact thì nên để tắt.
+
+**Ví dụ (bật):**
+
+```yaml
+tea_use_pactjs_utils: true
+```
+
+**Ví dụ (tắt):**
+
+```yaml
+tea_use_pactjs_utils: false
+```
+
+**Điều kiện tiên quyết:**
+
+```bash
+npm install -D @seontechnologies/pactjs-utils @pact-foundation/pact
+```
+
+**Liên quan:**
+
+- [Tài liệu Pact.js Utils](https://seontechnologies.github.io/pactjs-utils/)
+- [TEA Overview - Tích hợp tùy chọn](/vi-vn/explanation/tea-overview.md)
+
+---
+
+### tea_pact_mcp
+
+Chiến lược dùng Pact MCP để tương tác với broker trong các workflow contract testing.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `string`
+
+**Mặc định:** `"none"`
+
+**Tùy chọn:** `"mcp"` | `"none"`
+
+**Câu hỏi từ installer:**
+
+```text
+Enable SmartBear MCP for PactFlow/Pact Broker? Only needed if you already use a broker.
+```
+
+**Mục đích:** Quy định TEA có được phép dùng SmartBear MCP tool cho các việc như:
+
+- Khám phá provider-state trong workflow design/generation
+- Hỗ trợ review Pact test
+- Hướng dẫn can-i-deploy và matrix trong workflow CI
+
+**Ảnh hưởng tới workflow:**
+
+- `test-design` - nạp ngữ cảnh contract có broker
+- `automate` - hỗ trợ ngữ cảnh sinh pact với broker
+- `test-review` - hỗ trợ review pact với MCP
+- `ci` - tham chiếu can-i-deploy/matrix với MCP
+
+**Dùng khi nào:** Khi dự án đang dùng PactFlow hoặc Pact Broker và bạn muốn TEA truy vấn trạng thái broker trong lúc review, sinh test hoặc hỗ trợ gate. Nếu không, hãy để `none`.
+
+**Điều kiện tiên quyết:**
+
+```bash
+npm install -g @smartbear/mcp
+# hoặc: npx -y @smartbear/mcp@latest
+```
+
+**Biến môi trường bắt buộc cho broker (khi dùng tính năng Pact):**
+
+- `PACT_BROKER_BASE_URL`
+- `PACT_BROKER_TOKEN` (hoặc username/password nếu dùng basic auth)
+
+**Ví dụ (bật MCP):**
+
+```yaml
+tea_pact_mcp: 'mcp'
+```
+
+**Ví dụ (tắt MCP):**
+
+```yaml
+tea_pact_mcp: 'none'
+```
+
+**Liên quan:**
+
+- [Hướng dẫn cấu hình Browser Automation](/vi-vn/how-to/customization/configure-browser-automation.md)
+- [Tài liệu SmartBear MCP](https://developer.smartbear.com/smartbear-mcp/docs/getting-started)
+
+---
+
+### tea_browser_automation
+
+Chiến lược browser automation cho các workflow của TEA. Thiết lập này kiểm soát cách TEA tương tác với browser thật trong lúc tạo hoặc đánh giá test.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `string`
+
+**Mặc định:** `"auto"`
+
+**Tùy chọn:** `"auto"` | `"cli"` | `"mcp"` | `"none"`
+
+**Câu hỏi từ installer:**
+
+```text
+How should TEA interact with browsers during test generation?
+```
+
+**Mục đích:** Chọn công cụ browser automation TEA sẽ dùng:
+
+| Chế độ | Hành vi |
+| ------ | -------------------------------------------------------------------------------------------------------------------- |
+| `auto` | Chọn thông minh - CLI cho tác vụ stateless, MCP cho luồng cần giữ trạng thái. Có fallback an toàn. **(Khuyến nghị)** |
+| `cli` | Chỉ dùng CLI (`@playwright/cli`). Bỏ qua MCP. |
+| `mcp` | Chỉ dùng MCP. Bỏ qua CLI. Tương đương hành vi cũ của `tea_use_mcp_enhancements: true`. |
+| `none` | Không tương tác với browser. Chỉ sinh bằng AI từ docs/code. |
+
+**Ảnh hưởng tới workflow:**
+
+- `test-design` - exploratory mode
+- `atdd` - recording mode
+- `automate` - healing mode và recording mode
+- `test-review` - thu thập bằng chứng như trace, screenshot
+
+**Điều kiện tiên quyết:**
+
+- **CLI:** `npm install -g @playwright/cli@latest` rồi `playwright-cli install --skills`
+- **MCP:** cấu hình MCP server trong IDE, xem [Configure Browser Automation](/vi-vn/how-to/customization/configure-browser-automation.md)
+
+**Ví dụ (auto - khuyến nghị):**
+
+```yaml
+tea_browser_automation: 'auto'
+```
+
+**Ví dụ (chỉ CLI):**
+
+```yaml
+tea_browser_automation: 'cli'
+```
+
+**Ví dụ (chỉ MCP - giống hành vi cũ):**
+
+```yaml
+tea_browser_automation: 'mcp'
+```
+
+**Ví dụ (tắt):**
+
+```yaml
+tea_browser_automation: 'none'
+```
+
+**Chuyển đổi từ cờ cũ:**
+
+| Thiết lập cũ | Tương đương mới |
+| --------------------------------- | -------------------------------- |
+| `tea_use_mcp_enhancements: true` | `tea_browser_automation: "auto"` |
+| `tea_use_mcp_enhancements: false` | `tea_browser_automation: "none"` |
+
+---
+
+### tea_execution_mode
+
+Chiến lược thực thi cho các workflow TEA có khả năng orchestration.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `string`
+
+**Mặc định:** `"auto"`
+
+**Tùy chọn:** `"auto"` | `"subagent"` | `"agent-team"` | `"sequential"`
+
+**Câu hỏi từ installer:**
+
+```text
+How should TEA orchestrate multi-step generation and evaluation?
+```
+
+**Mục đích:** Xác định cách TEA điều phối các bước kiểu worker trong các workflow:
+
+- `automate`
+- `atdd`
+- `test-review`
+- `nfr-assess`
+- `framework`
+- `ci`
+- `test-design`
+- `trace`
+
+`teach-me-testing` không dùng thiết lập này.
+
+**Hành vi từng chế độ:**
+
+| Chế độ | Hành vi |
+| ------------ | ------------------------------------------------------------------------------------------ |
+| `auto` | Khuyến nghị. TEA tự chọn chế độ tốt nhất dựa trên capability runtime nếu probing được bật. |
+| `agent-team` | Ưu tiên orchestration theo runtime team/delegation. |
+| `subagent` | Ưu tiên orchestration theo kiểu subagent tách biệt. |
+| `sequential` | Bắt buộc chạy tuần tự từng bước. Ổn định nhất nhưng thường chậm nhất. |
+
+**Lưu ý quan trọng:** Ở `agent-team` và `subagent`, runtime sẽ quyết định scheduling và concurrency. TEA không tự áp thêm giới hạn worker song song.
+
+**Ảnh hưởng theo workflow:**
+
+| Workflow | Đơn vị được orchestration | Chế độ ảnh hưởng thế nào |
+| ------------- | ------------------------------------- | -------------------------- |
+| `automate` | API + E2E/backend generation workers | Chỉ thay đổi cách dispatch |
+| `atdd` | worker sinh failing API + failing E2E | Chỉ thay đổi cách dispatch |
+| `test-review` | worker theo từng chiều chất lượng | Chỉ thay đổi cách dispatch |
+| `nfr-assess` | worker đánh giá từng miền | Chỉ thay đổi cách dispatch |
+| `framework` | các work unit tạo scaffold | Chỉ thay đổi cách dispatch |
+| `ci` | bước sinh pipeline có orchestration | Chính sách orchestration |
+| `test-design` | bước sinh output có orchestration | Chính sách orchestration |
+| `trace` | tách phase/work-unit có dependency | Chính sách orchestration |
+
+Hợp đồng đầu ra của mỗi workflow không đổi giữa các chế độ.
+
+**Thứ tự resolve:**
+
+1. Chuẩn hóa cách diễn đạt ở lần chạy hiện tại nếu có:
+ - `agent team` / `agent teams` / `agentteam` -> `agent-team`
+ - `subagent` / `subagents` / `sub agent` / `sub agents` -> `subagent`
+ - `sequential` -> `sequential`
+ - `auto` -> `auto`
+2. Nếu không có override ở lần chạy hiện tại, dùng `tea_execution_mode` trong `_bmad/tea/config.yaml`.
+3. Nếu `tea_capability_probe: true`, phát hiện runtime có hỗ trợ `agent-team` hay `subagent` hay không.
+4. Resolve mode:
+ - `auto` -> `agent-team` -> `subagent` -> `sequential`
+ - với `agent-team`/`subagent` tường minh -> chỉ fallback khi probing được bật
+ - `sequential` -> luôn chạy tuần tự
+
+**Ví dụ (khuyến nghị):**
+
+```yaml
+tea_execution_mode: 'auto'
+```
+
+**Ví dụ (bắt buộc tuần tự):**
+
+```yaml
+tea_execution_mode: 'sequential'
+```
+
+---
+
+### tea_capability_probe
+
+TEA có nên kiểm tra capability của runtime trước khi resolve execution mode hay không.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `boolean`
+
+**Mặc định:** `true`
+
+**Mục đích:** Khi bật, TEA sẽ kiểm tra runtime có thực sự hỗ trợ `agent-team` hoặc `subagent` hay không và fallback an toàn khi cần. Khi tắt, TEA sẽ bám cứng cấu hình và fail nếu runtime không hỗ trợ.
+
+**Ví dụ (khuyến nghị):**
+
+```yaml
+tea_capability_probe: true
+```
+
+**Ví dụ (strict):**
+
+```yaml
+tea_capability_probe: false
+```
+
+---
+
+### test_stack_type
+
+Loại stack của dự án, có thể được phát hiện tự động hoặc cấu hình tường minh. Thiết lập này ảnh hưởng tới CI pipeline và chọn framework.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `string`
+
+**Mặc định:** `"auto"`
+
+**Tùy chọn:** `"auto"` | `"frontend"` | `"backend"` | `"fullstack"`
+
+**Mục đích:** Điều khiển hành vi theo loại stack:
+
+| Loại stack | Hành vi |
+| ----------- | ----------------------------------------------------------------- |
+| `auto` | Tự phát hiện từ manifest/config của dự án |
+| `frontend` | Browser-based test, cài browser trong CI, burn-in thường được bật |
+| `backend` | API/unit test, không cài browser, burn-in thường bỏ qua |
+| `fullstack` | Có cả frontend lẫn backend, pipeline đầy đủ |
+
+**Ảnh hưởng tới workflow:**
+
+- `ci` - pipeline thay đổi theo loại stack
+- `framework` - scaffold thay đổi theo stack
+
+**Ví dụ:**
+
+```yaml
+test_stack_type: 'fullstack'
+```
+
+---
+
+### ci_platform
+
+Nền tảng CI/CD được dùng để sinh pipeline.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `string`
+
+**Mặc định:** `"auto"`
+
+**Tùy chọn:** `"auto"` | `"github-actions"` | `"gitlab-ci"` | `"jenkins"` | `"azure-devops"` | `"harness"` | `"circle-ci"` | `"other"`
+
+**Mục đích:** Điều khiển template CI mà TEA sẽ dùng để sinh pipeline.
+
+Khi đặt `"auto"`, TEA sẽ tự phát hiện bằng cách quét các file cấu hình CI hiện có như `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`, `.harness/`, `.circleci/config.yml`, rồi fallback sang suy luận từ git remote nếu cần.
+
+**Ảnh hưởng tới workflow:**
+
+- `ci` - chọn template và đường dẫn output
+
+**Ví dụ:**
+
+```yaml
+ci_platform: 'github-actions'
+```
+
+---
+
+### test_framework
+
+Test framework được phát hiện tự động hoặc cấu hình tường minh.
+
+**Vị trí schema:** `src/module.yaml` (cấu hình module TEA)
+
+**Cấu hình người dùng:** `_bmad/tea/config.yaml`
+
+**Kiểu:** `string`
+
+**Mặc định:** `"auto"`
+
+**Tùy chọn:** `"auto"` | `"playwright"` | `"cypress"` | `"jest"` | `"vitest"` | `"pytest"` | `"junit"` | `"go-test"` | `"dotnet-test"` | `"rspec"` | `"other"`
+
+**Mục đích:** Điều khiển pattern framework mà TEA dùng cho code generation. Khi đặt `"auto"`, TEA sẽ tự phát hiện từ file cấu hình và manifest của dự án. Hỗ trợ cả frontend framework như Playwright/Cypress/Jest/Vitest và backend framework như pytest/JUnit/Go test/dotnet test/RSpec.
+
+**Ảnh hưởng tới workflow:**
+
+- `framework` - scaffold
+- `ci` - câu lệnh test trong pipeline
+- `atdd` - pattern sinh test code
+- `automate` - pattern sinh test code
+
+**Ví dụ:**
+
+```yaml
+test_framework: 'playwright'
+```
+
+---
+
+## Cấu hình BMM cốt lõi mà TEA kế thừa
+
+TEA cũng dùng các tùy chọn cấu hình BMM cốt lõi từ `_bmad/tea/config.yaml`.
+
+### output_folder
+
+**Kiểu:** `string`
+
+**Mặc định:** `_bmad-output`
+
+**Mục đích:** Thư mục output gốc cho artifact cốt lõi của BMM. TEA sẽ ghi artifact kiểm thử vào `test_artifacts` (mặc định là `{output_folder}/test-artifacts`).
+
+**Ví dụ:**
+
+```yaml
+output_folder: _bmad-output
+```
+
+**Các file đầu ra của TEA (nằm trong `{test_artifacts}`):**
+
+- `test-design-architecture.md` + `test-design-qa.md`
+- `test-design-epic-N.md`
+- `test-review.md`
+- `traceability-matrix.md`
+- `gate-decision-{gate_type}-{story_id}.md`
+- `nfr-assessment.md`
+- `automation-summary.md`
+- `atdd-checklist-{story_key}.md`
+
+### user_skill_level
+
+**Kiểu:** `enum`
+
+**Tùy chọn:** `beginner` | `intermediate` | `expert`
+
+**Mặc định:** `intermediate`
+
+**Mục đích:** Ảnh hưởng cách TEA giải thích trong chat.
+
+**Ví dụ:**
+
+```yaml
+user_skill_level: beginner
+```
+
+**Ảnh hưởng tới TEA:**
+
+- **Beginner:** giải thích nhiều hơn, dẫn khái niệm, verbose hơn
+- **Intermediate:** cân bằng giữa ngắn gọn và hướng dẫn
+- **Expert:** súc tích, kỹ thuật, ít dẫn dắt
+
+### project_name
+
+**Kiểu:** `string`
+
+**Mặc định:** Tên thư mục hiện tại
+
+**Mục đích:** Dùng trong tài liệu và report do TEA tạo ra.
+
+**Ví dụ:**
+
+```yaml
+project_name: my-awesome-app
+```
+
+### communication_language
+
+**Kiểu:** `string`
+
+**Mặc định:** `english`
+
+**Mục đích:** Ngôn ngữ TEA dùng để phản hồi trong chat.
+
+**Ví dụ:**
+
+```yaml
+communication_language: vietnamese
+```
+
+### document_output_language
+
+**Kiểu:** `string`
+
+**Mặc định:** `english`
+
+**Mục đích:** Ngôn ngữ TEA dùng để sinh tài liệu như test design hoặc report.
+
+**Ví dụ:**
+
+```yaml
+document_output_language: vietnamese
+```
+
+**Lưu ý:** Có thể khác với `communication_language`. Ví dụ chat bằng tiếng Việt nhưng tạo tài liệu bằng tiếng Anh.
+
+---
+
+## Biến môi trường
+
+Workflow của TEA có thể dùng biến môi trường để cấu hình test.
+
+### Biến cho test framework
+
+**Playwright:**
+
+```bash
+# .env
+BASE_URL=https://todomvc.com/examples/react/dist/
+API_BASE_URL=https://api.example.com
+TEST_USER_EMAIL=test@example.com
+TEST_USER_PASSWORD=password123
+```
+
+**Cypress:**
+
+```bash
+# cypress.env.json or .env
+CYPRESS_BASE_URL=https://example.com
+CYPRESS_API_URL=https://api.example.com
+```
+
+### Biến cho CI/CD
+
+Khai báo trong CI platform, ví dụ GitHub Actions secrets:
+
+```yaml
+# .github/workflows/test.yml
+env:
+ BASE_URL: ${{ secrets.STAGING_URL }}
+ API_KEY: ${{ secrets.API_KEY }}
+ TEST_USER_EMAIL: ${{ secrets.TEST_USER }}
+```
+
+---
+
+## Pattern cấu hình
+
+### Development và Production
+
+**Tách cấu hình theo môi trường:**
+
+```yaml
+# _bmad/tea/config.yaml
+output_folder: _bmad-output
+
+# .env.development
+BASE_URL=http://localhost:3000
+API_BASE_URL=http://localhost:4000
+
+# .env.staging
+BASE_URL=https://staging.example.com
+API_BASE_URL=https://api-staging.example.com
+
+# .env.production (chỉ dùng test read-only!)
+BASE_URL=https://example.com
+API_BASE_URL=https://api.example.com
+```
+
+### Team và cá nhân
+
+**Cấu hình đội (được commit):**
+
+```yaml
+# _bmad/tea/config.yaml.example
+project_name: team-project
+output_folder: _bmad-output
+tea_use_playwright_utils: true
+tea_browser_automation: 'none'
+tea_execution_mode: 'sequential'
+```
+
+**Cấu hình cá nhân (thường được gitignore):**
+
+```yaml
+# _bmad/tea/config.yaml
+user_name: John Doe
+user_skill_level: expert
+tea_browser_automation: 'auto'
+tea_execution_mode: 'auto'
+```
+
+### Monorepo
+
+**Cấu hình ở root:**
+
+```yaml
+# _bmad/tea/config.yaml
+project_name: monorepo-parent
+output_folder: _bmad-output
+```
+
+**Cấu hình theo package:**
+
+```yaml
+# packages/web-app/_bmad/tea/config.yaml
+project_name: web-app
+output_folder: ../../_bmad-output/web-app
+tea_use_playwright_utils: true
+
+# packages/mobile-app/_bmad/tea/config.yaml
+project_name: mobile-app
+output_folder: ../../_bmad-output/mobile-app
+tea_use_playwright_utils: false
+```
+
+---
+
+## Best practice cấu hình
+
+### 1. Dùng version control hợp lý
+
+**Nên commit:**
+
+```text
+_bmad/tea/config.yaml.example
+.nvmrc
+package.json
+```
+
+**Khuyến nghị thêm vào `.gitignore`:**
+
+```text
+_bmad/tea/config.yaml
+.env
+.env.local
+```
+
+### 2. Ghi rõ setup bắt buộc
+
+**Trong README:**
+
+```markdown
+## Setup
+
+1. Install BMad
+
+2. Copy config template:
+ cp \_bmad/tea/config.yaml.example \_bmad/tea/config.yaml
+
+3. Edit config with your values:
+ - Set user_name
+ - Enable tea_use_playwright_utils if using playwright-utils
+ - Set tea_browser_automation mode (auto, cli, mcp, or none)
+ - Set tea_execution_mode (auto, subagent, agent-team, or sequential)
+```
+
+### 3. Xác thực cấu hình
+
+**Kiểm tra cấu hình hợp lệ:**
+
+```bash
+# Check TEA config is set
+cat _bmad/tea/config.yaml | grep tea_use
+
+# Verify playwright-utils installed (if enabled)
+npm list @seontechnologies/playwright-utils
+
+# Verify MCP servers configured (if enabled)
+# Check your IDE's MCP settings
+```
+
+### 4. Giữ cấu hình ở mức tối giản
+
+**Không over-configure:**
+
+```yaml
+# ❌ Không tốt - override quá nhiều thứ
+project_name: my-project
+user_name: John Doe
+user_skill_level: expert
+output_folder: custom/path
+planning_artifacts: custom/planning
+implementation_artifacts: custom/implementation
+project_knowledge: custom/docs
+tea_use_playwright_utils: true
+tea_browser_automation: "auto"
+tea_execution_mode: "auto"
+communication_language: english
+document_output_language: english
+
+# ✅ Tốt - chỉ override phần thực sự cần
+tea_use_playwright_utils: true
+tea_execution_mode: "auto"
+output_folder: docs/testing
+```
+
+Hãy dùng mặc định khi có thể.
+
+---
+
+## Khắc phục sự cố
+
+### Cấu hình không được nạp
+
+**Vấn đề:** TEA không dùng giá trị cấu hình của tôi.
+
+**Nguyên nhân có thể:**
+
+1. File cấu hình nằm sai vị trí
+2. YAML sai cú pháp
+3. Sai tên khóa cấu hình
+
+**Cách xử lý:**
+
+```bash
+ls -la _bmad/tea/config.yaml
+js-yaml _bmad/tea/config.yaml
+diff _bmad/tea/config.yaml src/module.yaml
+```
+
+### Playwright Utils không hoạt động
+
+**Vấn đề:** `tea_use_playwright_utils: true` nhưng TEA không dùng utility.
+
+**Nguyên nhân có thể:**
+
+1. Chưa cài package
+2. Chưa lưu file cấu hình
+3. Chạy workflow trước khi cập nhật config
+
+**Cách xử lý:**
+
+```bash
+npm list @seontechnologies/playwright-utils
+grep tea_use_playwright_utils _bmad/tea/config.yaml
+```
+
+Sau đó chạy lại workflow trong chat mới.
+
+### Browser automation không hoạt động
+
+**Vấn đề:** `tea_browser_automation` đặt là `"auto"` / `"cli"` / `"mcp"` nhưng browser không mở.
+
+**Nguyên nhân có thể:**
+
+1. Chưa cài CLI toàn cục
+2. Chưa cấu hình MCP server trong IDE
+3. Thiếu browser binary
+
+**Cách xử lý:**
+
+```bash
+playwright-cli --version
+npx @playwright/mcp@latest --version
+npx playwright install
+```
+
+### Thay đổi config không có hiệu lực
+
+**Nguyên nhân:** TEA nạp config ở đầu workflow.
+
+**Cách xử lý:**
+
+1. Lưu `_bmad/tea/config.yaml`
+2. Mở chat mới
+3. Chạy lại workflow
+
+---
+
+## Ví dụ cấu hình
+
+### Thiết lập khuyến nghị (full stack)
+
+```yaml
+# _bmad/tea/config.yaml
+project_name: my-project
+user_skill_level: beginner
+output_folder: _bmad-output
+tea_use_playwright_utils: true
+tea_use_pactjs_utils: false
+tea_pact_mcp: 'none'
+tea_browser_automation: 'auto'
+tea_execution_mode: 'auto'
+tea_capability_probe: true
+```
+
+**Vì sao nên dùng:**
+
+- Playwright Utils: có fixture và utility sẵn sàng cho production
+- Pact.js Utils: chỉ nên bật khi dự án thực sự dùng contract testing
+- Browser automation ở chế độ `auto`: chọn CLI/MCP thông minh và có fallback
+
+### Thiết lập tối giản (chỉ để học)
+
+```yaml
+project_name: my-project
+output_folder: _bmad-output
+tea_use_playwright_utils: false
+tea_use_pactjs_utils: false
+tea_pact_mcp: 'none'
+tea_browser_automation: 'none'
+tea_execution_mode: 'sequential'
+tea_capability_probe: true
+```
+
+### Thiết lập monorepo
+
+```yaml
+# _bmad/tea/config.yaml (root)
+project_name: monorepo
+output_folder: _bmad-output
+tea_use_playwright_utils: true
+tea_use_pactjs_utils: false
+tea_pact_mcp: 'none'
+tea_execution_mode: 'auto'
+```
+
+### Template cho đội
+
+```yaml
+# _bmad/tea/config.yaml.example
+project_name: your-project-name
+user_name: Your Name
+user_skill_level: intermediate
+output_folder: _bmad-output
+planning_artifacts: _bmad-output/planning-artifacts
+implementation_artifacts: _bmad-output/implementation-artifacts
+project_knowledge: docs
+tea_use_playwright_utils: true
+tea_use_pactjs_utils: false
+tea_pact_mcp: 'none'
+tea_browser_automation: 'auto'
+tea_execution_mode: 'auto'
+tea_capability_probe: true
+communication_language: english
+document_output_language: english
+```
+
+### Thiết lập contract testing (opt-in)
+
+Chỉ dùng profile này cho service đã dùng Pact hoặc muốn TEA scaffold pattern contract testing một cách chủ động.
+
+```yaml
+tea_use_pactjs_utils: true
+tea_pact_mcp: 'none'
+```
+
+Nếu đồng thời dùng PactFlow hoặc Pact Broker:
+
+```yaml
+tea_use_pactjs_utils: true
+tea_pact_mcp: 'mcp'
+```
+
+---
+
+## Xem thêm
+
+### How-To Guides
+
+- [Set Up Test Framework](/vi-vn/how-to/workflows/setup-test-framework.md)
+- [Integrate Playwright Utils](/vi-vn/how-to/customization/integrate-playwright-utils.md)
+- [Configure Browser Automation](/vi-vn/how-to/customization/configure-browser-automation.md)
+
+### Reference
+
+- [TEA Command Reference](/vi-vn/reference/commands.md)
+- [Knowledge Base Index](/vi-vn/reference/knowledge-base.md)
+- [Glossary](/vi-vn/glossary/index.md)
+
+### Explanation
+
+- [TEA Overview](/vi-vn/explanation/tea-overview.md)
+- [Testing as Engineering](/vi-vn/explanation/testing-as-engineering.md)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/reference/knowledge-base.md b/docs/vi-vn/reference/knowledge-base.md
new file mode 100644
index 0000000..75ab4e6
--- /dev/null
+++ b/docs/vi-vn/reference/knowledge-base.md
@@ -0,0 +1,284 @@
+---
+title: 'Chỉ mục Knowledge Base của TEA'
+description: Chỉ mục đầy đủ của 42 knowledge fragment mà TEA dùng cho context engineering
+---
+
+# Chỉ mục Knowledge Base của TEA
+
+TEA sử dụng 42 knowledge fragment chuyên biệt cho context engineering. Các fragment này được nạp động theo nhu cầu của workflow thông qua manifest `tea-index.csv`.
+
+## Context Engineering là gì?
+
+**Context engineering** là cách đưa các tiêu chuẩn chuyên biệt của domain vào context AI một cách có hệ thống, thay vì chỉ dựa vào prompt.
+
+Thay vì luôn phải nhắc AI “hãy viết test tốt”, TEA sẽ:
+
+1. Đọc `tea-index.csv` để biết fragment nào liên quan đến workflow hiện tại
+2. Chỉ nạp fragment cần thiết để giữ context tập trung
+3. Vận hành theo tiêu chuẩn kiểm thử chuyên biệt thay vì tri thức chung chung
+4. Tạo ra test và artifact nhất quán, sẵn sàng cho production
+
+**Ví dụ:**
+
+```text
+User runs: test-design
+
+TEA reads tea-index.csv:
+- Loads: test-quality.md, test-priorities-matrix.md, risk-governance.md
+- Skips: network-recorder.md, burn-in.md
+```
+
+## Cách knowledge loading hoạt động
+
+### 1. Workflow được kích hoạt
+
+Người dùng chạy workflow, ví dụ `test-design`.
+
+### 2. Tra manifest
+
+TEA đọc file:
+
+`src/agents/bmad-tea/resources/tea-index.csv`
+
+Ví dụ:
+
+```csv
+id,name,description,tags,tier,fragment_file
+test-quality,Test Quality,Execution limits and isolation rules,"quality,standards",core,knowledge/test-quality.md
+risk-governance,Risk Governance,Risk scoring and gate decisions,"risk,governance",core,knowledge/risk-governance.md
+```
+
+### 3. Nạp fragment động
+
+Chỉ fragment cần cho workflow được đưa vào context.
+
+### 4. Tạo đầu ra nhất quán
+
+AI hoạt động theo pattern đã được chuẩn hóa, nên đầu ra ổn định hơn nhiều.
+
+## Nhóm fragment
+
+### Architecture & Fixtures
+
+Pattern hạ tầng kiểm thử và fixture composition.
+
+- `fixture-architecture` - Pure function → Fixture → mergeTests
+- `network-first` - intercept-before-navigate, HAR capture, deterministic wait
+- `playwright-config` - môi trường, timeout, artifact
+- `fixtures-composition` - mergeTests và tổ chức fixture
+
+**Dùng trong:** `framework`, `test-design`, `atdd`, `automate`, `test-review`
+
+### Data & Setup
+
+- `data-factories` - factory pattern, faker, cleanup
+- `email-auth` - magic link, email flow
+- `auth-session` - token persistence, multi-user, auth pattern
+
+**Dùng trong:** `framework`, `atdd`, `automate`, `test-review`
+
+### Network & Reliability
+
+- `network-recorder` - HAR record/playback
+- `intercept-network-call` - network spy/stub, parse JSON
+- `error-handling` - retry validation, scoped exception handling
+- `network-error-monitor` - phát hiện HTTP 4xx/5xx
+
+**Dùng trong:** `atdd`, `automate`, `test-review`
+
+### Test Execution & CI
+
+- `ci-burn-in`
+- `burn-in`
+- `selective-testing`
+
+**Dùng trong:** `ci`, `test-review`
+
+### Quality & Standards
+
+- `test-quality`
+- `test-levels-framework`
+- `test-priorities-matrix`
+- `test-healing-patterns`
+- `component-tdd`
+
+**Dùng trong:** `test-design`, `atdd`, `automate`, `test-review`, `trace`
+
+### Risk & Gates
+
+- `risk-governance`
+- `probability-impact`
+- `nfr-criteria`
+- `adr-quality-readiness-checklist`
+
+**Dùng trong:** `test-design`, `nfr-assess`, `trace`
+
+### Selectors & Timing
+
+- `selector-resilience`
+- `timing-debugging`
+- `visual-debugging`
+
+**Dùng trong:** `atdd`, `automate`, `test-review`
+
+### Feature Flags & API Patterns
+
+- `feature-flags`
+- `api-testing-patterns`
+
+**Dùng trong:** `test-design`, `atdd`, `automate`
+
+### Pact & Contract Testing Integration
+
+Nhóm fragment cho contract testing và tích hợp Pact:
+
+- `contract-testing`
+- `pactjs-utils-overview`
+- `pactjs-utils-consumer-helpers`
+- `pactjs-utils-provider-verifier`
+- `pactjs-utils-request-filter`
+- `pact-mcp`
+- `pact-consumer-framework-setup`
+- `pact-consumer-di`
+
+**Dùng trong:** `framework`, `test-design`, `atdd`, `automate`, `test-review`, `ci`
+
+### Browser Automation
+
+- `playwright-cli` - automation qua CLI cho agent
+
+**Dùng trong:** `atdd`, `automate`, `test-design`, `test-review`, `nfr-assess`
+
+### Playwright Utils Integration
+
+Pattern dùng `@seontechnologies/playwright-utils`:
+
+- `api-request`
+- `auth-session`
+- `network-recorder`
+- `intercept-network-call`
+- `recurse`
+- `log`
+- `file-utils`
+- `burn-in`
+- `network-error-monitor`
+- `overview`
+
+**Dùng trong:** `framework`, `atdd`, `automate`, `test-review`, `ci`
+
+## Manifest fragment (`tea-index.csv`)
+
+**Vị trí:** `src/agents/bmad-tea/resources/tea-index.csv`
+
+**Mục đích:** Theo dõi tất cả fragment và workflow nào sử dụng chúng.
+
+**Cột dữ liệu:**
+
+- `id` - định danh duy nhất
+- `name` - tên dễ đọc
+- `description` - fragment bao phủ nội dung gì
+- `tags` - tag hỗ trợ tìm kiếm
+- `tier` - mức ưu tiên khi nạp
+- `fragment_file` - đường dẫn tương đối tới file markdown
+
+### Loading profile
+
+- **Core tier**: nạp tự động khi workflow bắt đầu
+- **Extended tier**: nạp khi ngữ cảnh yêu cầu
+- **Specialized tier**: chỉ nạp khi use case thật sự khớp
+
+## Workflow nào nạp fragment nào
+
+### `framework`
+
+Fragment chính:
+
+- `fixture-architecture.md`
+- `playwright-config.md`
+- `fixtures-composition.md`
+
+### `test-design`
+
+Fragment chính:
+
+- `test-quality.md`
+- `test-priorities-matrix.md`
+- `test-levels-framework.md`
+- `risk-governance.md`
+- `probability-impact.md`
+
+### `atdd`
+
+Fragment chính:
+
+- `test-quality.md`
+- `component-tdd.md`
+- `fixture-architecture.md`
+- `network-first.md`
+- `data-factories.md`
+- `selector-resilience.md`
+- `timing-debugging.md`
+- `test-healing-patterns.md`
+
+### `automate`
+
+Fragment chính:
+
+- `test-quality.md`
+- `test-levels-framework.md`
+- `test-priorities-matrix.md`
+- `fixture-architecture.md`
+- `network-first.md`
+- `selector-resilience.md`
+- `test-healing-patterns.md`
+- `timing-debugging.md`
+
+### `test-review`
+
+Fragment chính:
+
+- `test-quality.md`
+- `test-healing-patterns.md`
+- `selector-resilience.md`
+- `timing-debugging.md`
+- `visual-debugging.md`
+- `network-first.md`
+- `test-levels-framework.md`
+- `fixture-architecture.md`
+
+### `ci`
+
+Fragment chính:
+
+- `ci-burn-in.md`
+- `burn-in.md`
+- `selective-testing.md`
+- `playwright-config.md`
+
+### `nfr-assess`
+
+Fragment chính:
+
+- `nfr-criteria.md`
+- `risk-governance.md`
+- `probability-impact.md`
+
+### `trace`
+
+Fragment chính:
+
+- `test-priorities-matrix.md`
+- `risk-governance.md`
+- `test-quality.md`
+
+Nếu gate decision có xét NFR thì `nfr-criteria.md` cũng sẽ được nạp.
+
+## Tài liệu liên quan
+
+- [TEA Overview](/vi-vn/explanation/tea-overview.md)
+- [Testing as Engineering](/vi-vn/explanation/testing-as-engineering.md)
+- [TEA Command Reference](/vi-vn/reference/commands.md)
+
+---
+
+Tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/docs/vi-vn/reference/troubleshooting.md b/docs/vi-vn/reference/troubleshooting.md
new file mode 100644
index 0000000..77ae2b2
--- /dev/null
+++ b/docs/vi-vn/reference/troubleshooting.md
@@ -0,0 +1,404 @@
+---
+title: Hướng dẫn khắc phục sự cố
+description: Chẩn đoán và xử lý các vấn đề thường gặp khi sử dụng TEA
+---
+
+# Hướng dẫn khắc phục sự cố
+
+Tài liệu này giúp bạn chẩn đoán và xử lý các vấn đề thường gặp khi dùng TEA (Test Engineering Architect).
+
+## Mục lục
+
+- Installation Issues
+- Agent Loading Issues
+- Workflow Execution Issues
+- Knowledge Base Issues
+- Configuration Issues
+- Output and File Issues
+- Integration Issues
+- Performance Issues
+- Getting Help
+
+---
+
+## Vấn đề cài đặt
+
+### Không thấy module TEA sau khi cài
+
+**Triệu chứng:** Chạy `npx bmad-method install` xong nhưng không thấy agent TEA.
+
+**Nguyên nhân có thể:**
+
+- Bạn chưa chọn TEA khi cài
+- Quá trình cài thất bại âm thầm
+- Thư mục `_bmad/tea/` chưa được tạo
+
+**Cách xử lý:**
+
+```bash
+ls -la _bmad/tea/
+npx bmad-method install
+npx bmad-method install --verbose
+```
+
+### Cài TEA sau firewall công ty
+
+Nếu installer chạy được nhưng không thể tải module TEA từ GitHub, hãy trỏ sang local clone hoặc internal mirror.
+
+1. Clone TEA về local hoặc mirror nội bộ
+2. Sửa `external-official-modules.yaml` để `url:` trỏ tới local path
+3. Chạy lại installer
+
+### Cài đặt bị treo
+
+**Nguyên nhân thường gặp:**
+
+- Mạng có vấn đề
+- NPM timeout
+- Thiếu dung lượng đĩa
+
+**Cách xử lý:**
+
+```bash
+ping registry.npmjs.org
+df -h
+npm cache clean --force
+npx bmad-method install
+```
+
+---
+
+## Vấn đề nạp agent
+
+### Lỗi “Agent not found”
+
+**Triệu chứng:** báo lỗi agent `tea` hoặc `_bmad/tea` không tìm thấy.
+
+**Cách xử lý:**
+
+```bash
+ls -la _bmad/tea/agents/bmad-tea/SKILL.md
+node tools/validate-agent-schema.js
+rm -rf _bmad/tea/
+npx bmad-method install
+```
+
+### TEA nạp được nhưng command không chạy
+
+**Nguyên nhân có thể:**
+
+- Thiếu workflow file
+- Sai đường dẫn workflow
+- YAML lỗi cú pháp
+
+**Cách xử lý:**
+
+```bash
+ls -la _bmad/tea/workflows/testarch/
+cat _bmad/tea/workflows/testarch/bmad-testarch-test-design/workflow.yaml
+```
+
+Thử gọi trực tiếp:
+
+```text
+/bmad:tea:test-design
+$bmad-tea-testarch-test-design
+```
+
+### Workflow tùy chỉnh không còn xuất hiện
+
+TEA hiện là module tách riêng. Custom workflow sẽ không tự merge vào core nữa.
+
+**Cách xử lý:**
+
+1. Đóng gói workflow thành custom content hoặc custom module
+2. Gắn vào `bmad-tea` bằng file customization dưới `_bmad/_config/agents/`
+3. Chạy lại `npx bmad-method install`
+
+---
+
+## Vấn đề khi chạy workflow
+
+### Workflow chạy nhưng không sinh output
+
+**Nguyên nhân có thể:**
+
+- Output directory chưa có hoặc không ghi được
+- `test_artifacts` chưa cấu hình đúng
+- Workflow dừng trước bước output generation
+
+**Cách xử lý:**
+
+```bash
+cat _bmad/tea/module.yaml | grep test_artifacts
+mkdir -p test-results
+ls -la test-results/
+```
+
+### Subagent thất bại
+
+**Nguyên nhân có thể:**
+
+- Thiếu step file
+- Không ghi được temp file
+- Output format của subagent không hợp lệ
+- Runtime không hỗ trợ execution mode hiện tại
+
+**Cách xử lý:**
+
+```bash
+ls -la _bmad/tea/workflows/testarch/bmad-testarch-automate/steps-c/step-03*.md
+ls -la /tmp/ | grep bmad-tea
+grep -E "tea_execution_mode|tea_capability_probe" _bmad/tea/config.yaml
+```
+
+Nếu cần fallback an toàn:
+
+```yaml
+tea_execution_mode: 'sequential'
+tea_capability_probe: true
+```
+
+### Knowledge fragment không được nạp
+
+**Nguyên nhân có thể:**
+
+- Thiếu hoặc hỏng `tea-index.csv`
+- Thiếu file fragment
+- Workflow không khai báo fragment đúng
+
+**Cách xử lý:**
+
+```bash
+cat _bmad/tea/agents/bmad-tea/resources/tea-index.csv | wc -l
+ls -la _bmad/tea/agents/bmad-tea/resources/knowledge/ | wc -l
+head -5 _bmad/tea/agents/bmad-tea/resources/tea-index.csv
+grep -A 5 "knowledge_fragments" _bmad/tea/workflows/testarch/bmad-testarch-test-design/workflow.yaml
+```
+
+---
+
+## Vấn đề cấu hình
+
+### Không thấy prompt cấu hình khi cài
+
+**Nguyên nhân có thể:**
+
+- `prompt: false` trong `module.yaml`
+- Installer đang chạy non-interactive
+- `module.yaml` bị cấu hình sai
+
+**Cách xử lý:**
+
+```bash
+cat _bmad/tea/module.yaml | grep -A 3 "test_artifacts"
+npx bmad-method install --interactive
+```
+
+### Playwright Utils không hoạt động
+
+**Nguyên nhân có thể:**
+
+- `tea_use_playwright_utils` đang là `false`
+- Thiếu knowledge fragment liên quan
+- Workflow đang dùng không hỗ trợ tích hợp này
+
+**Cách xử lý:**
+
+```bash
+cat _bmad/tea/module.yaml | grep tea_use_playwright_utils
+grep -i "playwright-utils" _bmad/tea/agents/bmad-tea/resources/tea-index.csv
+```
+
+---
+
+## Vấn đề output và file
+
+### Test được sinh ra sai vị trí
+
+**Nguyên nhân có thể:**
+
+- `test_artifacts` cấu hình sai
+- Nhầm đường dẫn tương đối
+- Working directory bị thay đổi
+
+**Cách xử lý:**
+
+```bash
+cat _bmad/tea/module.yaml | grep test_artifacts
+pwd
+```
+
+### Test sinh ra bị lỗi cú pháp
+
+**Nguyên nhân có thể:**
+
+- Mismatch framework (Playwright/Cypress)
+- Nạp sai template
+- Knowledge fragment bị lỗi
+
+**Cách xử lý:**
+
+```text
+Generate Playwright tests using TypeScript
+```
+
+Sau đó kiểm tra:
+
+```bash
+npx eslint tests/**/*.spec.ts
+markdownlint _bmad/tea/agents/bmad-tea/resources/knowledge/*.md
+```
+
+### Lỗi quyền file
+
+**Cách xử lý:**
+
+```bash
+ls -la test-results/
+chmod -R u+w test-results/
+df -h
+```
+
+---
+
+## Vấn đề tích hợp
+
+### Không tìm thấy Playwright Utils
+
+**Nguyên nhân có thể:**
+
+- Package chưa cài
+- Sai import path
+- Sai version
+
+**Cách xử lý:**
+
+```bash
+npm install @muratkeremozcan/playwright-utils
+npm ls @muratkeremozcan/playwright-utils
+```
+
+### Browser automation không hoạt động
+
+**Triệu chứng:** `tea_browser_automation` đặt là `"auto"` / `"cli"` / `"mcp"` nhưng đầu ra không có browser feature.
+
+**Cách xử lý:**
+
+```bash
+playwright-cli --version
+cat _bmad/tea/config.yaml | grep tea_browser_automation
+```
+
+Kiểm tra MCP config trong IDE và khởi động lại IDE sau khi sửa.
+
+---
+
+## Vấn đề hiệu năng
+
+### Workflow chạy quá lâu
+
+**Nguyên nhân có thể:**
+
+- Codebase lớn
+- Review quá nhiều test cùng lúc
+- Overhead do subagent
+- Mạng chậm
+
+**Cách xử lý:**
+
+- Thu hẹp phạm vi review
+- Chạy theo thư mục thay vì toàn bộ suite
+- Tập trung vào workflow mục tiêu thay vì audit toàn phần
+
+### Nạp knowledge base chậm
+
+Điều này có thể là hành vi bình thường khi workflow phải nạp nhiều fragment. Lần chạy sau thường nhanh hơn do cache tốt hơn.
+
+---
+
+## Khi cần trợ giúp
+
+### Bật debug mode
+
+```bash
+export DEBUG=bmad:tea:*
+```
+
+### Thu thập thông tin chẩn đoán
+
+Khi báo lỗi, nên kèm:
+
+1. Phiên bản TEA
+2. Phiên bản BMAD
+3. Phiên bản Node
+4. Hệ điều hành
+5. Cấu trúc thư mục `_bmad/tea/`
+6. Toàn bộ error message
+7. Các bước tái hiện
+
+### Kênh hỗ trợ
+
+- Documentation:
+- GitHub Issues:
+- GitHub Discussions:
+
+## Error message thường gặp
+
+### `Module 'tea' not found`
+
+Reinstall TEA bằng `npx bmad-method install`.
+
+### `Knowledge fragment 'test-quality' not found`
+
+Kiểm tra `tea-index.csv` và danh sách fragment.
+
+### `Cannot write to test-results/`
+
+Tạo thư mục và sửa quyền.
+
+### `Workflow 'test-design' failed at step 3`
+
+Kiểm tra step file tồn tại hay không.
+
+### `Agent YAML validation failed`
+
+Chạy:
+
+```bash
+node tools/validate-agent-schema.js
+```
+
+### `Subagent execution timeout`
+
+Thu hẹp phạm vi workflow hoặc chuyển sang chế độ `sequential`.
+
+## Troubleshooting nâng cao
+
+### Script kiểm tra thủ công cài đặt TEA
+
+```bash
+#!/bin/bash
+echo "Validating TEA Installation..."
+
+if [ -f "_bmad/tea/agents/bmad-tea/SKILL.md" ]; then
+ echo "✓ Agent skill exists"
+else
+ echo "✗ Agent skill missing"
+fi
+```
+
+Bạn có thể mở rộng script này để kiểm tra workflow, knowledge fragment và `tea-index.csv`.
+
+### Reset TEA về trạng thái sạch
+
+```bash
+cp _bmad/tea/module.yaml /tmp/tea-module-backup.yaml
+rm -rf _bmad/tea/
+npx bmad-method install
+cp /tmp/tea-module-backup.yaml _bmad/tea/module.yaml
+```
+
+---
+
+Nếu vẫn bị kẹt, hãy mở GitHub Issue kèm thông tin chẩn đoán.
diff --git a/docs/vi-vn/tutorials/learn-testing-tea-academy.md b/docs/vi-vn/tutorials/learn-testing-tea-academy.md
new file mode 100644
index 0000000..71f245e
--- /dev/null
+++ b/docs/vi-vn/tutorials/learn-testing-tea-academy.md
@@ -0,0 +1,199 @@
+---
+title: 'Học kiểm thử với TEA Academy'
+description: Bắt đầu hành trình học kiểm thử với TEA Academy - 7 buổi học tăng tiến từ nền tảng đến nâng cao
+---
+
+# Học kiểm thử với TEA Academy
+
+**Thời gian:** 1-2 tuần (tự học, 7 buổi)
+**Đối tượng:** QA/QC, developer, lead, manager - bất kỳ ai đang học kiểm thử
+**Mục tiêu:** Tiếp cận kiểm thử theo lộ trình tăng tiến, từ cơ bản đến thực hành nâng cao với TEA
+
+## TEA Academy là gì?
+
+TEA Academy là một trợ lý học tập tương tác, dạy kiểm thử qua 7 buổi có cấu trúc. Khác với việc chỉ đọc tài liệu, TEA Academy:
+
+- **Dạy học theo từng bước**: Xây dựng kiến thức theo từng buổi
+- **Kiểm tra mức độ hiểu**: Mỗi buổi có quiz, đạt từ 70% trở lên
+- **Theo dõi tiến độ**: Có thể tạm dừng và tiếp tục bất cứ lúc nào
+- **Tùy biến theo vai trò**: Ví dụ được điều chỉnh cho QA/Dev/Lead/VP
+- **Sinh artifact học tập**: Ghi chú từng buổi và chứng nhận hoàn thành
+
+## Bắt đầu nhanh
+
+### 1. Nạp agent TEA
+
+```bash
+tea
+```
+
+### 2. Khởi động TEA Academy
+
+```bash
+TMT
+```
+
+Hoặc:
+
+```bash
+teach-me-testing
+```
+
+### 3. Hoàn thành đánh giá đầu vào
+
+Bạn sẽ trả lời 4 câu hỏi:
+
+- Vai trò hiện tại
+- Mức kinh nghiệm
+- Mục tiêu học tập
+- Pain points trong công việc (không bắt buộc)
+
+### 4. Chọn buổi học đầu tiên
+
+Menu sẽ hiển thị đủ 7 buổi:
+
+- **Người mới:** Buổi 1
+- **Đã có nền tảng:** Buổi 2 hoặc 3
+- **Người có kinh nghiệm:** Có thể vào thẳng Buổi 7
+
+### 5. Hoàn thành các buổi
+
+Mỗi buổi sẽ:
+
+- Dạy khái niệm kèm ví dụ
+- Kiểm tra bằng quiz 3 câu
+- Tạo session notes
+- Tự động lưu tiến độ
+
+### 6. Nhận chứng nhận
+
+Hoàn thành 7 buổi để nhận chứng nhận TEA Academy.
+
+## 7 buổi học
+
+### Buổi 1: Khởi động nhanh
+
+- TEA là gì và vì sao tồn tại
+- Cách tiếp cận TEA Lite trong 30 phút
+- Tổng quan 9 workflow
+- 5 engagement model
+
+### Buổi 2: Khái niệm cốt lõi
+
+- Tư duy "testing as engineering"
+- Risk-based testing và ma trận P0-P3
+- Cách chấm điểm Probability × Impact
+- Definition of Done với 7 nguyên tắc chất lượng
+
+### Buổi 3: Kiến trúc và pattern
+
+- Fixture composition
+- Network-first patterns
+- Data factory
+- Step-file architecture
+
+### Buổi 4: Test Design
+
+- Workflow Test Design
+- Đánh giá rủi ro và khả năng kiểm thử
+- Chiến lược lập kế hoạch coverage
+- Hệ thống test level
+
+### Buổi 5: ATDD và Automate
+
+- Workflow ATDD theo TDD red-green
+- Workflow Automate để mở rộng coverage
+- Pattern TDD cho component
+- API testing không phụ thuộc browser
+
+### Buổi 6: Quality và Trace
+
+- Workflow Test Review theo 5 chiều đánh giá
+- Chấm điểm chất lượng 0-100
+- Workflow Trace để truy vết coverage
+- Quy trình release gate
+
+### Buổi 7: Pattern nâng cao
+
+- Khám phá 42 knowledge fragment theo menu
+- Đào sâu pattern khi cần
+- Đường dẫn tới repo GitHub để tự nghiên cứu
+
+## Theo dõi tiến độ
+
+### Lưu tự động
+
+Tiến độ được lưu sau khi:
+
+- Hoàn tất đánh giá đầu vào
+- Xong quiz
+- Tạo session notes
+- Chủ động thoát workflow
+
+### Tiếp tục học
+
+Khi chạy lại workflow, TEA sẽ:
+
+- Nhận biết tiến độ đã có
+- Hiển thị dashboard trạng thái
+- Gợi ý tiếp tục từ điểm đang dở
+
+### Artifact được tạo
+
+```text
+{test_artifacts}/
+├── teaching-progress/
+│ └── {your-name}-tea-progress.yaml
+└── tea-academy/
+ └── {your-name}/
+ ├── session-01-notes.md
+ ├── session-02-notes.md
+ ├── ...
+ ├── session-07-notes.md
+ └── tea-completion-certificate.md
+```
+
+## Lộ trình theo vai trò
+
+### QA Engineer
+
+- Trọng tâm: sử dụng workflow thực tế, mở rộng coverage, quality metrics
+- Nên học: cả 7 buổi
+
+### Developer
+
+- Trọng tâm: TDD, integration testing, API testing
+- Nên học: 1, 2, 5, 3, 4
+
+### Tech Lead
+
+- Trọng tâm: kiến trúc test, standard đội nhóm, review
+- Nên học: 1, 3, 4, 6, 7
+
+### VP/Manager
+
+- Trọng tâm: chiến lược kiểm thử, ROI, khả năng mở rộng đội nhóm, metric
+- Nên học: 1, 2, 4, 6
+
+## Câu hỏi thường gặp
+
+**Mất bao lâu?**
+Người mới cần 1-2 tuần để học hết 7 buổi. Người đã có kinh nghiệm có thể hoàn thành trong 3-4 giờ nếu học đúng nội dung cần thiết.
+
+**Có được bỏ qua buổi học không?**
+Có. Bạn có thể nhảy đến bất kỳ buổi nào từ menu.
+
+**Nếu fail quiz thì sao?**
+Bạn có thể học lại, làm lại, hoặc đi tiếp. Điểm vẫn được lưu.
+
+**Có học lại được không?**
+Có. Chạy lại workflow và chọn buổi cần học lại.
+
+## Bước tiếp theo
+
+Sau khi học xong TEA Academy, bạn có thể:
+
+1. Chạy [Framework Setup](/vi-vn/how-to/workflows/setup-test-framework) để dựng test framework
+2. Chạy [Test Design](/vi-vn/how-to/workflows/run-test-design) để lập kế hoạch coverage
+3. Chạy [ATDD](/vi-vn/how-to/workflows/run-atdd) hoặc [Automate](/vi-vn/how-to/workflows/run-automate) để tạo test
+4. Khám phá thêm knowledge fragments khi cần học sâu
diff --git a/docs/vi-vn/tutorials/tea-lite-quickstart.md b/docs/vi-vn/tutorials/tea-lite-quickstart.md
new file mode 100644
index 0000000..20d2e21
--- /dev/null
+++ b/docs/vi-vn/tutorials/tea-lite-quickstart.md
@@ -0,0 +1,297 @@
+---
+title: 'Bắt đầu với Test Architect'
+description: Học các nguyên tắc cơ bản của Test Architect bằng cách tạo và chạy test cho một ứng dụng demo có sẵn trong 30 phút
+---
+
+Chào mừng! **TEA Lite** là cách đơn giản nhất để bắt đầu với TEA. Bạn chỉ cần dùng workflow `automate` để tạo test cho các tính năng đã tồn tại. Cách này đặc biệt phù hợp với người mới muốn thấy TEA tạo giá trị nhanh.
+
+## Bạn sẽ tạo ra gì
+
+Kết thúc tutorial khoảng 30 phút này, bạn sẽ có:
+
+- Một Playwright test framework hoạt động được
+- Bản test plan đầu tiên dựa trên rủi ro
+- Một bộ test pass cho một feature của ứng dụng demo có sẵn
+
+:::note[Điều kiện tiên quyết]
+
+- Đã cài Node.js phiên bản 20 trở lên
+- Có khoảng 30 phút tập trung
+- Demo app dùng trong bài là TodoMVC:
+ :::
+
+:::tip[Lộ trình nhanh]
+Nạp TEA (`tea`) → scaffold framework (`framework`) → tạo test plan (`test-design`) → sinh test (`automate`) → chạy bằng `npx playwright test`.
+:::
+
+## Các cách tiếp cận TEA
+
+Trước khi bắt đầu, nên hiểu nhanh ba cách dùng phổ biến:
+
+- **TEA Lite**: cách dành cho người mới, tập trung vào `automate` để test feature hiện có
+- **TEA Solo**: dùng TEA độc lập mà không cần full BMad Method
+- **TEA Integrated**: tích hợp TEA trọn vẹn qua nhiều phase của BMad Method
+
+Tutorial này tập trung vào **TEA Lite**, vì đây là con đường ngắn nhất để thấy TEA hoạt động thực tế.
+
+## Bước 0: Chuẩn bị, khoảng 2 phút
+
+Chúng ta sẽ test TodoMVC, một demo app phổ biến trong tài liệu testing.
+
+**Demo app:**
+
+Không cần cài đặt local cho ứng dụng này. Chỉ cần mở link trong trình duyệt và thử:
+
+1. Tạo một vài todo bằng cách nhập nội dung rồi nhấn Enter
+2. Đánh dấu một vài todo là hoàn thành
+3. Thử các bộ lọc `All`, `Active`, `Completed`
+
+Bạn vừa khám phá đúng những feature mà chúng ta sắp test.
+
+## Bước 1: Cài BMad và scaffold framework, khoảng 10 phút
+
+### Cài BMad Method
+
+Cài BMad theo hướng dẫn cài đặt mới nhất của dự án.
+
+Khi trình cài đặt hỏi:
+
+- **Select modules:** chọn `BMM: BMad Method`
+- **Project name:** để mặc định hoặc nhập tên dự án
+- **Experience level:** chọn `beginner` cho tutorial này
+- **Planning artifacts folder:** giữ mặc định
+- **Implementation artifacts folder:** giữ mặc định
+- **Project knowledge folder:** giữ mặc định
+- **Enable TEA Playwright Model Context Protocol (MCP) enhancements?** chọn `No` ở lần đầu
+- **Using playwright-utils?** chọn `No` ở lần đầu
+
+Sau khi cài xong, bạn sẽ thấy thư mục `_bmad/` trong project.
+
+### Nạp TEA agent
+
+Bắt đầu một chat mới với AI assistant của bạn rồi gõ:
+
+```text
+tea
+```
+
+Thao tác này nạp Test Architect agent và hiển thị menu các workflow khả dụng.
+
+### Scaffold test framework
+
+Trong chat với TEA, chạy:
+
+```text
+framework
+```
+
+TEA sẽ hỏi một số câu như:
+
+**Q: Tech stack của bạn là gì?**
+**A:** "We’re testing a React web application (TodoMVC)"
+
+**Q: Muốn dùng framework nào?**
+**A:** "Playwright"
+
+**Q: Testing scope là gì?**
+**A:** "End-to-end (E2E) testing for a web application"
+
+**Q: Nền tảng CI/CD nào?**
+**A:** "GitHub Actions" hoặc lựa chọn bạn đang dùng
+
+TEA sẽ sinh:
+
+- thư mục `tests/`
+- `playwright.config.ts`
+- cấu trúc sample test
+- `.env.example`
+- `.nvmrc`
+
+**Xác minh setup:**
+
+```bash
+npm install
+npx playwright install
+```
+
+Sau bước này, bạn đã có test framework ở mức production-ready cơ bản.
+
+## Bước 2: Test design đầu tiên, khoảng 5 phút
+
+Đây là nơi TEA bắt đầu thể hiện điểm khác biệt: lập kế hoạch kiểm thử dựa trên rủi ro trước khi viết test.
+
+### Chạy Test Design
+
+Trong chat với TEA, chạy:
+
+```text
+test-design
+```
+
+TEA có thể hỏi:
+
+**Q: System-level hay epic-level?**
+**A:** "Epic-level - I want to test TodoMVC's basic functionality"
+
+**Q: Bạn đang test feature nào?**
+**A:** "TodoMVC's core operations - creating, completing, and deleting todos"
+
+**Q: Có rủi ro hoặc mối quan tâm cụ thể nào không?**
+**A:** "We want to ensure the filter buttons (All, Active, Completed) work correctly"
+
+TEA sẽ phân tích và tạo `test-design-epic-1.md`, thường gồm:
+
+1. **Risk Assessment**
+ - chấm điểm probability × impact
+ - phân loại risk theo TECH, SEC, PERF, DATA, BUS, OPS
+ - xác định vùng rủi ro cao
+
+2. **Test Priorities**
+ - P0: critical path như tạo và hiển thị todo
+ - P1: high value như complete todo và filter
+ - P2: medium value như delete todo
+ - P3: low value hoặc edge case
+
+3. **Coverage Strategy**
+ - nên dùng E2E ra sao
+ - scenario nào bắt buộc phải test
+ - gợi ý cấu trúc suite
+
+Hãy mở file test design và đọc nó. Đây là điểm rất hữu ích cho QC vì nó trả lời rõ: **cần test gì trước và vì sao**.
+
+## Bước 3: Sinh test cho feature hiện có, khoảng 5 phút
+
+Đây là lúc TEA bắt đầu tạo test dựa trên kế hoạch vừa có.
+
+### Chạy Automate
+
+Trong chat với TEA, chạy:
+
+```text
+automate
+```
+
+Ví dụ câu trả lời:
+
+**Q: What are you testing?**
+**A:** "TodoMVC React app at - focus on the test design we just created"
+
+**Q: Reference existing docs?**
+**A:** "Yes, use test-design-epic-1.md"
+
+**Q: Any specific test scenarios?**
+**A:** "Cover the P0 and P1 scenarios from the test design"
+
+TEA sẽ sinh các file như:
+
+- `tests/e2e/todomvc.spec.ts`
+- `tests/README.md`
+- tóm tắt Definition of Done
+
+Ví dụ test được sinh:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('TodoMVC - Core Functionality', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('https://todomvc.com/examples/react/dist/');
+ });
+
+ test('should create a new todo', async ({ page }) => {
+ const todoInput = page.locator('.new-todo');
+ await todoInput.fill('Buy groceries');
+ await todoInput.press('Enter');
+
+ await expect(page.locator('.todo-list li')).toContainText('Buy groceries');
+ });
+
+ test('should mark todo as complete', async ({ page }) => {
+ const todoInput = page.locator('.new-todo');
+ await todoInput.fill('Complete tutorial');
+ await todoInput.press('Enter');
+
+ await page.locator('.todo-list li .toggle').click();
+ await expect(page.locator('.todo-list li')).toHaveClass(/completed/);
+ });
+
+ test('should filter todos by status', async ({ page }) => {
+ const todoInput = page.locator('.new-todo');
+ await todoInput.fill('Buy groceries');
+ await todoInput.press('Enter');
+ await todoInput.fill('Write tests');
+ await todoInput.press('Enter');
+
+ await page.locator('.todo-list li .toggle').first().click();
+
+ await page.locator('.filters a[href=\"#/active\"]').click();
+ await expect(page.locator('.todo-list li')).toHaveCount(1);
+ await expect(page.locator('.todo-list li')).toContainText('Write tests');
+
+ await page.locator('.filters a[href=\"#/completed\"]').click();
+ await expect(page.locator('.todo-list li')).toHaveCount(1);
+ await expect(page.locator('.todo-list li')).toContainText('Buy groceries');
+ });
+});
+```
+
+### Khi bật Playwright Utils
+
+Nếu cấu hình `tea_use_playwright_utils: true`, TEA có thể sinh test với utility production-ready thay vì chỉ dùng Playwright API cơ bản. Điều này đặc biệt hữu ích khi suite bắt đầu lớn hơn và cần fixture chuẩn hóa.
+
+## Bước 4: Chạy test, khoảng 3 phút
+
+Chạy toàn bộ test:
+
+```bash
+npx playwright test
+```
+
+Chạy với giao diện:
+
+```bash
+npx playwright test --ui
+```
+
+Chạy ở chế độ debug:
+
+```bash
+npx playwright test --debug
+```
+
+Nếu mọi thứ ổn, bạn sẽ thấy suite pass trên demo app.
+
+## Bạn vừa học được gì
+
+- TEA không sinh test theo kiểu ngẫu nhiên
+- `test-design` giúp QC ưu tiên đúng vùng cần bao phủ
+- `automate` dùng kế hoạch đó để mở rộng coverage sau implementation
+- `framework` giúp khởi tạo hạ tầng test theo hướng production-ready
+
+## Khi nào nên dừng ở TEA Lite
+
+TEA Lite là điểm khởi đầu rất tốt nếu:
+
+- bạn đang học TEA
+- muốn thấy kết quả nhanh
+- đang test feature đã có sẵn
+
+Nhưng nếu bạn cần:
+
+- failing acceptance tests trước khi dev
+- release gate có bằng chứng
+- audit test chất lượng trên toàn suite
+- NFR/compliance review
+
+thì bạn nên tiến lên `TEA Solo` hoặc `TEA Integrated`.
+
+## Bước tiếp theo
+
+- Muốn học có lộ trình hơn: [TEA Academy](/docs/vi-vn/tutorials/learn-testing-tea-academy.md)
+- Muốn hiểu toàn cảnh: [TEA Overview](/docs/vi-vn/explanation/tea-overview.md)
+- Muốn đi sâu vào workflow sinh test: [Automate Workflow](/docs/vi-vn/how-to/workflows/run-automate.md)
+- Muốn học lập kế hoạch test tốt hơn: [Run Test Design](/docs/vi-vn/how-to/workflows/run-test-design.md)
+
+---
+
+Được tạo bằng [BMad Method](https://bmad-method.org) - TEA (Test Engineering Architect)
diff --git a/website/astro.config.mjs b/website/astro.config.mjs
index 2e37f1d..2bed886 100644
--- a/website/astro.config.mjs
+++ b/website/astro.config.mjs
@@ -40,6 +40,17 @@ export default defineConfig({
starlight({
title: 'Test Architect (TEA)',
tagline: 'Risk-based test strategy, automation guidance, and release gate decisions for quality-driven development.',
+ defaultLocale: 'root',
+ locales: {
+ root: {
+ label: 'English',
+ lang: 'en',
+ },
+ 'vi-vn': {
+ label: 'Tiếng Việt',
+ lang: 'vi-VN',
+ },
+ },
favicon: '/favicon.ico',
@@ -85,72 +96,173 @@ export default defineConfig({
// Sidebar configuration (Diataxis structure)
sidebar: [
- { label: 'Welcome', slug: 'index' },
- { label: 'TEA Overview', slug: 'explanation/tea-overview' },
+ {
+ label: 'Welcome',
+ translations: { 'vi-VN': 'Chào mừng' },
+ slug: 'index',
+ },
+ {
+ label: 'TEA Overview',
+ translations: { 'vi-VN': 'Tổng quan TEA' },
+ slug: 'explanation/tea-overview',
+ },
{
label: 'Tutorials',
+ translations: { 'vi-VN': 'Hướng dẫn học' },
collapsed: false,
autogenerate: { directory: 'tutorials' },
},
{
label: 'How-To Guides',
+ translations: { 'vi-VN': 'Hướng dẫn thực hiện' },
collapsed: true,
items: [
{
label: 'Workflows',
+ translations: { 'vi-VN': 'Workflows' },
items: [
- { label: 'Teach Me Testing', slug: 'how-to/workflows/teach-me-testing' },
- { label: 'Set Up Test Framework', slug: 'how-to/workflows/setup-test-framework' },
- { label: 'Set Up CI Pipeline', slug: 'how-to/workflows/setup-ci' },
- { label: 'Test Design', slug: 'how-to/workflows/run-test-design' },
+ {
+ label: 'Teach Me Testing',
+ translations: { 'vi-VN': 'Học kiểm thử' },
+ slug: 'how-to/workflows/teach-me-testing',
+ },
+ {
+ label: 'Set Up Test Framework',
+ translations: { 'vi-VN': 'Thiết lập test framework' },
+ slug: 'how-to/workflows/setup-test-framework',
+ },
+ {
+ label: 'Set Up CI Pipeline',
+ translations: { 'vi-VN': 'Thiết lập CI pipeline' },
+ slug: 'how-to/workflows/setup-ci',
+ },
+ {
+ label: 'Test Design',
+ translations: { 'vi-VN': 'Thiết kế kiểm thử' },
+ slug: 'how-to/workflows/run-test-design',
+ },
{ label: 'ATDD', slug: 'how-to/workflows/run-atdd' },
- { label: 'Automate', slug: 'how-to/workflows/run-automate' },
- { label: 'Test Review', slug: 'how-to/workflows/run-test-review' },
- { label: 'Trace', slug: 'how-to/workflows/run-trace' },
- { label: 'NFR Assessment', slug: 'how-to/workflows/run-nfr-assess' },
+ {
+ label: 'Automate',
+ translations: { 'vi-VN': 'Tự động hóa' },
+ slug: 'how-to/workflows/run-automate',
+ },
+ {
+ label: 'Test Review',
+ translations: { 'vi-VN': 'Đánh giá test' },
+ slug: 'how-to/workflows/run-test-review',
+ },
+ {
+ label: 'Trace',
+ translations: { 'vi-VN': 'Truy vết' },
+ slug: 'how-to/workflows/run-trace',
+ },
+ {
+ label: 'NFR Assessment',
+ translations: { 'vi-VN': 'Đánh giá NFR' },
+ slug: 'how-to/workflows/run-nfr-assess',
+ },
],
},
{
label: 'Customization',
+ translations: { 'vi-VN': 'Tùy biến' },
autogenerate: { directory: 'how-to/customization' },
},
{
label: 'Brownfield Projects',
+ translations: { 'vi-VN': 'Dự án brownfield' },
autogenerate: { directory: 'how-to/brownfield' },
},
],
},
{
label: 'Explanation',
+ translations: { 'vi-VN': 'Giải thích' },
collapsed: true,
items: [
- { label: 'Testing as Engineering', slug: 'explanation/testing-as-engineering' },
- { label: 'Engagement Models', slug: 'explanation/engagement-models' },
- { label: 'Risk-Based Testing', slug: 'explanation/risk-based-testing' },
- { label: 'Test Quality Standards', slug: 'explanation/test-quality-standards' },
- { label: 'Knowledge Base System', slug: 'explanation/knowledge-base-system' },
- { label: 'Network-First Patterns', slug: 'explanation/network-first-patterns' },
- { label: 'Fixture Architecture', slug: 'explanation/fixture-architecture' },
- { label: 'Step-File Architecture', slug: 'explanation/step-file-architecture' },
- { label: 'Subagent Architecture', slug: 'explanation/subagent-architecture' },
+ {
+ label: 'Testing as Engineering',
+ translations: { 'vi-VN': 'Testing as Engineering' },
+ slug: 'explanation/testing-as-engineering',
+ },
+ {
+ label: 'Engagement Models',
+ translations: { 'vi-VN': 'Mô hình engagement' },
+ slug: 'explanation/engagement-models',
+ },
+ {
+ label: 'Risk-Based Testing',
+ translations: { 'vi-VN': 'Kiểm thử dựa trên rủi ro' },
+ slug: 'explanation/risk-based-testing',
+ },
+ {
+ label: 'Test Quality Standards',
+ translations: { 'vi-VN': 'Tiêu chuẩn chất lượng test' },
+ slug: 'explanation/test-quality-standards',
+ },
+ {
+ label: 'Knowledge Base System',
+ translations: { 'vi-VN': 'Hệ thống knowledge base' },
+ slug: 'explanation/knowledge-base-system',
+ },
+ {
+ label: 'Network-First Patterns',
+ translations: { 'vi-VN': 'Pattern network-first' },
+ slug: 'explanation/network-first-patterns',
+ },
+ {
+ label: 'Fixture Architecture',
+ translations: { 'vi-VN': 'Kiến trúc fixture' },
+ slug: 'explanation/fixture-architecture',
+ },
+ {
+ label: 'Step-File Architecture',
+ translations: { 'vi-VN': 'Kiến trúc step-file' },
+ slug: 'explanation/step-file-architecture',
+ },
+ {
+ label: 'Subagent Architecture',
+ translations: { 'vi-VN': 'Kiến trúc subagent' },
+ slug: 'explanation/subagent-architecture',
+ },
],
},
{
label: 'Reference',
+ translations: { 'vi-VN': 'Tham chiếu' },
collapsed: true,
items: [
- { label: 'Commands', slug: 'reference/commands' },
- { label: 'Configuration', slug: 'reference/configuration' },
- { label: 'Knowledge Base', slug: 'reference/knowledge-base' },
- { label: 'Troubleshooting', slug: 'reference/troubleshooting' },
+ {
+ label: 'Commands',
+ translations: { 'vi-VN': 'Lệnh' },
+ slug: 'reference/commands',
+ },
+ {
+ label: 'Configuration',
+ translations: { 'vi-VN': 'Cấu hình' },
+ slug: 'reference/configuration',
+ },
+ {
+ label: 'Knowledge Base',
+ translations: { 'vi-VN': 'Knowledge Base' },
+ slug: 'reference/knowledge-base',
+ },
+ {
+ label: 'Troubleshooting',
+ translations: { 'vi-VN': 'Khắc phục sự cố' },
+ slug: 'reference/troubleshooting',
+ },
],
},
{
label: 'Glossary',
+ translations: { 'vi-VN': 'Thuật ngữ' },
slug: 'glossary',
},
{
label: 'BMad Ecosystem',
+ translations: { 'vi-VN': 'Hệ sinh thái BMad' },
collapsed: false,
items: [
{ label: 'BMad Method', link: 'https://docs.bmad-method.org/', attrs: { target: '_blank' } },
diff --git a/website/package-lock.json b/website/package-lock.json
index 974ebf2..669e242 100644
--- a/website/package-lock.json
+++ b/website/package-lock.json
@@ -14,13 +14,74 @@
"sharp": "^0.33.5"
},
"devDependencies": {
- "@types/node": "^22.10.5"
+ "@astrojs/check": "^0.9.8",
+ "@types/node": "^22.10.5",
+ "typescript": "^5.9.3"
+ }
+ },
+ "node_modules/@astrojs/check": {
+ "version": "0.9.8",
+ "resolved": "https://registry.npmjs.org/@astrojs/check/-/check-0.9.8.tgz",
+ "integrity": "sha512-LDng8446QLS5ToKjRHd3bgUdirvemVVExV7nRyJfW2wV36xuv7vDxwy5NWN9zqeSEDgg0Tv84sP+T3yEq+Zlkw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@astrojs/language-server": "^2.16.5",
+ "chokidar": "^4.0.3",
+ "kleur": "^4.1.5",
+ "yargs": "^17.7.2"
+ },
+ "bin": {
+ "astro-check": "bin/astro-check.js"
+ },
+ "peerDependencies": {
+ "typescript": "^5.0.0"
+ }
+ },
+ "node_modules/@astrojs/check/node_modules/chokidar": {
+ "version": "4.0.3",
+ "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
+ "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "readdirp": "^4.0.1"
+ },
+ "engines": {
+ "node": ">= 14.16.0"
+ },
+ "funding": {
+ "url": "https://paulmillr.com/funding/"
+ }
+ },
+ "node_modules/@astrojs/check/node_modules/kleur": {
+ "version": "4.1.5",
+ "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz",
+ "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=6"
+ }
+ },
+ "node_modules/@astrojs/check/node_modules/readdirp": {
+ "version": "4.1.2",
+ "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
+ "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 14.18.0"
+ },
+ "funding": {
+ "type": "individual",
+ "url": "https://paulmillr.com/funding/"
}
},
"node_modules/@astrojs/compiler": {
- "version": "2.13.0",
- "resolved": "https://registry.npmjs.org/@astrojs/compiler/-/compiler-2.13.0.tgz",
- "integrity": "sha512-mqVORhUJViA28fwHYaWmsXSzLO9osbdZ5ImUfxBarqsYdMlPbqAqGJCxsNzvppp1BEzc1mJNjOVvQqeDN8Vspw==",
+ "version": "2.13.1",
+ "resolved": "https://registry.npmjs.org/@astrojs/compiler/-/compiler-2.13.1.tgz",
+ "integrity": "sha512-f3FN83d2G/v32ipNClRKgYv30onQlMZX1vCeZMjPsMMPl1mDpmbl0+N5BYo4S/ofzqJyS5hvwacEo0CCVDn/Qg==",
"license": "MIT"
},
"node_modules/@astrojs/internal-helpers": {
@@ -29,6 +90,48 @@
"integrity": "sha512-vreGnYSSKhAjFJCWAwe/CNhONvoc5lokxtRoZims+0wa3KbHBdPHSSthJsKxPd8d/aic6lWKpRTYGY/hsgK6EA==",
"license": "MIT"
},
+ "node_modules/@astrojs/language-server": {
+ "version": "2.16.6",
+ "resolved": "https://registry.npmjs.org/@astrojs/language-server/-/language-server-2.16.6.tgz",
+ "integrity": "sha512-N990lu+HSFiG57owR0XBkr02BYMgiLCshLf+4QG4v6jjSWkBeQGnzqi+E1L08xFPPJ7eEeXnxPXGLaVv5pa4Ug==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@astrojs/compiler": "^2.13.1",
+ "@astrojs/yaml2ts": "^0.2.3",
+ "@jridgewell/sourcemap-codec": "^1.5.5",
+ "@volar/kit": "~2.4.28",
+ "@volar/language-core": "~2.4.28",
+ "@volar/language-server": "~2.4.28",
+ "@volar/language-service": "~2.4.28",
+ "muggle-string": "^0.4.1",
+ "tinyglobby": "^0.2.15",
+ "volar-service-css": "0.0.70",
+ "volar-service-emmet": "0.0.70",
+ "volar-service-html": "0.0.70",
+ "volar-service-prettier": "0.0.70",
+ "volar-service-typescript": "0.0.70",
+ "volar-service-typescript-twoslash-queries": "0.0.70",
+ "volar-service-yaml": "0.0.70",
+ "vscode-html-languageservice": "^5.6.2",
+ "vscode-uri": "^3.1.0"
+ },
+ "bin": {
+ "astro-ls": "bin/nodeServer.js"
+ },
+ "peerDependencies": {
+ "prettier": "^3.0.0",
+ "prettier-plugin-astro": ">=0.11.0"
+ },
+ "peerDependenciesMeta": {
+ "prettier": {
+ "optional": true
+ },
+ "prettier-plugin-astro": {
+ "optional": true
+ }
+ }
+ },
"node_modules/@astrojs/markdown-remark": {
"version": "6.3.10",
"resolved": "https://registry.npmjs.org/@astrojs/markdown-remark/-/markdown-remark-6.3.10.tgz",
@@ -165,6 +268,16 @@
"node": "18.20.8 || ^20.3.0 || >=22.0.0"
}
},
+ "node_modules/@astrojs/yaml2ts": {
+ "version": "0.2.3",
+ "resolved": "https://registry.npmjs.org/@astrojs/yaml2ts/-/yaml2ts-0.2.3.tgz",
+ "integrity": "sha512-PJzRmgQzUxI2uwpdX2lXSHtP4G8ocp24/t+bZyf5Fy0SZLSF9f9KXZoMlFM/XCGue+B0nH/2IZ7FpBYQATBsCg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "yaml": "^2.8.2"
+ }
+ },
"node_modules/@babel/helper-string-parser": {
"version": "7.27.1",
"resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
@@ -241,6 +354,68 @@
"node": ">=14"
}
},
+ "node_modules/@emmetio/abbreviation": {
+ "version": "2.3.3",
+ "resolved": "https://registry.npmjs.org/@emmetio/abbreviation/-/abbreviation-2.3.3.tgz",
+ "integrity": "sha512-mgv58UrU3rh4YgbE/TzgLQwJ3pFsHHhCLqY20aJq+9comytTXUDNGG/SMtSeMJdkpxgXSXunBGLD8Boka3JyVA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@emmetio/scanner": "^1.0.4"
+ }
+ },
+ "node_modules/@emmetio/css-abbreviation": {
+ "version": "2.1.8",
+ "resolved": "https://registry.npmjs.org/@emmetio/css-abbreviation/-/css-abbreviation-2.1.8.tgz",
+ "integrity": "sha512-s9yjhJ6saOO/uk1V74eifykk2CBYi01STTK3WlXWGOepyKa23ymJ053+DNQjpFcy1ingpaO7AxCcwLvHFY9tuw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@emmetio/scanner": "^1.0.4"
+ }
+ },
+ "node_modules/@emmetio/css-parser": {
+ "version": "0.4.1",
+ "resolved": "https://registry.npmjs.org/@emmetio/css-parser/-/css-parser-0.4.1.tgz",
+ "integrity": "sha512-2bC6m0MV/voF4CTZiAbG5MWKbq5EBmDPKu9Sb7s7nVcEzNQlrZP6mFFFlIaISM8X6514H9shWMme1fCm8cWAfQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@emmetio/stream-reader": "^2.2.0",
+ "@emmetio/stream-reader-utils": "^0.1.0"
+ }
+ },
+ "node_modules/@emmetio/html-matcher": {
+ "version": "1.3.0",
+ "resolved": "https://registry.npmjs.org/@emmetio/html-matcher/-/html-matcher-1.3.0.tgz",
+ "integrity": "sha512-NTbsvppE5eVyBMuyGfVu2CRrLvo7J4YHb6t9sBFLyY03WYhXET37qA4zOYUjBWFCRHO7pS1B9khERtY0f5JXPQ==",
+ "dev": true,
+ "license": "ISC",
+ "dependencies": {
+ "@emmetio/scanner": "^1.0.0"
+ }
+ },
+ "node_modules/@emmetio/scanner": {
+ "version": "1.0.4",
+ "resolved": "https://registry.npmjs.org/@emmetio/scanner/-/scanner-1.0.4.tgz",
+ "integrity": "sha512-IqRuJtQff7YHHBk4G8YZ45uB9BaAGcwQeVzgj/zj8/UdOhtQpEIupUhSk8dys6spFIWVZVeK20CzGEnqR5SbqA==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@emmetio/stream-reader": {
+ "version": "2.2.0",
+ "resolved": "https://registry.npmjs.org/@emmetio/stream-reader/-/stream-reader-2.2.0.tgz",
+ "integrity": "sha512-fXVXEyFA5Yv3M3n8sUGT7+fvecGrZP4k6FnWWMSZVQf69kAq0LLpaBQLGcPR30m3zMmKYhECP4k/ZkzvhEW5kw==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@emmetio/stream-reader-utils": {
+ "version": "0.1.0",
+ "resolved": "https://registry.npmjs.org/@emmetio/stream-reader-utils/-/stream-reader-utils-0.1.0.tgz",
+ "integrity": "sha512-ZsZ2I9Vzso3Ho/pjZFsmmZ++FWeEd/txqybHTm4OgaZzdS8V9V/YYWQwg5TC38Z7uLWUV1vavpLLbjJtKubR1A==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/@emnapi/runtime": {
"version": "1.8.1",
"resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.8.1.tgz",
@@ -1830,6 +2005,104 @@
"integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==",
"license": "ISC"
},
+ "node_modules/@volar/kit": {
+ "version": "2.4.28",
+ "resolved": "https://registry.npmjs.org/@volar/kit/-/kit-2.4.28.tgz",
+ "integrity": "sha512-cKX4vK9dtZvDRaAzeoUdaAJEew6IdxHNCRrdp5Kvcl6zZOqb6jTOfk3kXkIkG3T7oTFXguEMt5+9ptyqYR84Pg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@volar/language-service": "2.4.28",
+ "@volar/typescript": "2.4.28",
+ "typesafe-path": "^0.2.2",
+ "vscode-languageserver-textdocument": "^1.0.11",
+ "vscode-uri": "^3.0.8"
+ },
+ "peerDependencies": {
+ "typescript": "*"
+ }
+ },
+ "node_modules/@volar/language-core": {
+ "version": "2.4.28",
+ "resolved": "https://registry.npmjs.org/@volar/language-core/-/language-core-2.4.28.tgz",
+ "integrity": "sha512-w4qhIJ8ZSitgLAkVay6AbcnC7gP3glYM3fYwKV3srj8m494E3xtrCv6E+bWviiK/8hs6e6t1ij1s2Endql7vzQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@volar/source-map": "2.4.28"
+ }
+ },
+ "node_modules/@volar/language-server": {
+ "version": "2.4.28",
+ "resolved": "https://registry.npmjs.org/@volar/language-server/-/language-server-2.4.28.tgz",
+ "integrity": "sha512-NqcLnE5gERKuS4PUFwlhMxf6vqYo7hXtbMFbViXcbVkbZ905AIVWhnSo0ZNBC2V127H1/2zP7RvVOVnyITFfBw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@volar/language-core": "2.4.28",
+ "@volar/language-service": "2.4.28",
+ "@volar/typescript": "2.4.28",
+ "path-browserify": "^1.0.1",
+ "request-light": "^0.7.0",
+ "vscode-languageserver": "^9.0.1",
+ "vscode-languageserver-protocol": "^3.17.5",
+ "vscode-languageserver-textdocument": "^1.0.11",
+ "vscode-uri": "^3.0.8"
+ }
+ },
+ "node_modules/@volar/language-service": {
+ "version": "2.4.28",
+ "resolved": "https://registry.npmjs.org/@volar/language-service/-/language-service-2.4.28.tgz",
+ "integrity": "sha512-Rh/wYCZJrI5vCwMk9xyw/Z+MsWxlJY1rmMZPsxUoJKfzIRjS/NF1NmnuEcrMbEVGja00aVpCsInJfixQTMdvLw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@volar/language-core": "2.4.28",
+ "vscode-languageserver-protocol": "^3.17.5",
+ "vscode-languageserver-textdocument": "^1.0.11",
+ "vscode-uri": "^3.0.8"
+ }
+ },
+ "node_modules/@volar/source-map": {
+ "version": "2.4.28",
+ "resolved": "https://registry.npmjs.org/@volar/source-map/-/source-map-2.4.28.tgz",
+ "integrity": "sha512-yX2BDBqJkRXfKw8my8VarTyjv48QwxdJtvRgUpNE5erCsgEUdI2DsLbpa+rOQVAJYshY99szEcRDmyHbF10ggQ==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@volar/typescript": {
+ "version": "2.4.28",
+ "resolved": "https://registry.npmjs.org/@volar/typescript/-/typescript-2.4.28.tgz",
+ "integrity": "sha512-Ja6yvWrbis2QtN4ClAKreeUZPVYMARDYZl9LMEv1iQ1QdepB6wn0jTRxA9MftYmYa4DQ4k/DaSZpFPUfxl8giw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@volar/language-core": "2.4.28",
+ "path-browserify": "^1.0.1",
+ "vscode-uri": "^3.0.8"
+ }
+ },
+ "node_modules/@vscode/emmet-helper": {
+ "version": "2.11.0",
+ "resolved": "https://registry.npmjs.org/@vscode/emmet-helper/-/emmet-helper-2.11.0.tgz",
+ "integrity": "sha512-QLxjQR3imPZPQltfbWRnHU6JecWTF1QSWhx3GAKQpslx7y3Dp6sIIXhKjiUJ/BR9FX8PVthjr9PD6pNwOJfAzw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "emmet": "^2.4.3",
+ "jsonc-parser": "^2.3.0",
+ "vscode-languageserver-textdocument": "^1.0.1",
+ "vscode-languageserver-types": "^3.15.1",
+ "vscode-uri": "^3.0.8"
+ }
+ },
+ "node_modules/@vscode/l10n": {
+ "version": "0.0.18",
+ "resolved": "https://registry.npmjs.org/@vscode/l10n/-/l10n-0.0.18.tgz",
+ "integrity": "sha512-KYSIHVmslkaCDyw013pphY+d7x1qV8IZupYfeIfzNA+nsaWHbn5uPuQRvdRFsa9zFzGeudPuoGoZ1Op4jrJXIQ==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/acorn": {
"version": "8.15.0",
"resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
@@ -1851,6 +2124,38 @@
"acorn": "^6.0.0 || ^7.0.0 || ^8.0.0"
}
},
+ "node_modules/ajv": {
+ "version": "8.18.0",
+ "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
+ "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "fast-deep-equal": "^3.1.3",
+ "fast-uri": "^3.0.1",
+ "json-schema-traverse": "^1.0.0",
+ "require-from-string": "^2.0.2"
+ },
+ "funding": {
+ "type": "github",
+ "url": "https://github.com/sponsors/epoberezkin"
+ }
+ },
+ "node_modules/ajv-draft-04": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz",
+ "integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==",
+ "dev": true,
+ "license": "MIT",
+ "peerDependencies": {
+ "ajv": "^8.5.0"
+ },
+ "peerDependenciesMeta": {
+ "ajv": {
+ "optional": true
+ }
+ }
+ },
"node_modules/ansi-align": {
"version": "3.0.1",
"resolved": "https://registry.npmjs.org/ansi-align/-/ansi-align-3.0.1.tgz",
@@ -2688,6 +2993,100 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
+ "node_modules/cliui": {
+ "version": "8.0.1",
+ "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
+ "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
+ "dev": true,
+ "license": "ISC",
+ "dependencies": {
+ "string-width": "^4.2.0",
+ "strip-ansi": "^6.0.1",
+ "wrap-ansi": "^7.0.0"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/cliui/node_modules/ansi-regex": {
+ "version": "5.0.1",
+ "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+ "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/cliui/node_modules/ansi-styles": {
+ "version": "4.3.0",
+ "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+ "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "color-convert": "^2.0.1"
+ },
+ "engines": {
+ "node": ">=8"
+ },
+ "funding": {
+ "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+ }
+ },
+ "node_modules/cliui/node_modules/emoji-regex": {
+ "version": "8.0.0",
+ "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+ "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/cliui/node_modules/string-width": {
+ "version": "4.2.3",
+ "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+ "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "emoji-regex": "^8.0.0",
+ "is-fullwidth-code-point": "^3.0.0",
+ "strip-ansi": "^6.0.1"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/cliui/node_modules/strip-ansi": {
+ "version": "6.0.1",
+ "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+ "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "ansi-regex": "^5.0.1"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/cliui/node_modules/wrap-ansi": {
+ "version": "7.0.0",
+ "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+ "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "ansi-styles": "^4.0.0",
+ "string-width": "^4.1.0",
+ "strip-ansi": "^6.0.0"
+ },
+ "engines": {
+ "node": ">=10"
+ },
+ "funding": {
+ "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+ }
+ },
"node_modules/clsx": {
"version": "2.1.1",
"resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
@@ -3098,6 +3497,23 @@
"node": ">=4"
}
},
+ "node_modules/emmet": {
+ "version": "2.4.11",
+ "resolved": "https://registry.npmjs.org/emmet/-/emmet-2.4.11.tgz",
+ "integrity": "sha512-23QPJB3moh/U9sT4rQzGgeyyGIrcM+GH5uVYg2C6wZIxAIJq7Ng3QLT79tl8FUwDXhyq9SusfknOrofAKqvgyQ==",
+ "dev": true,
+ "license": "MIT",
+ "workspaces": [
+ "./packages/scanner",
+ "./packages/abbreviation",
+ "./packages/css-abbreviation",
+ "./"
+ ],
+ "dependencies": {
+ "@emmetio/abbreviation": "^2.3.3",
+ "@emmetio/css-abbreviation": "^2.1.8"
+ }
+ },
"node_modules/emoji-regex": {
"version": "10.6.0",
"resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz",
@@ -3195,6 +3611,16 @@
"@esbuild/win32-x64": "0.25.12"
}
},
+ "node_modules/escalade": {
+ "version": "3.2.0",
+ "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+ "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=6"
+ }
+ },
"node_modules/escape-string-regexp": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz",
@@ -3322,6 +3748,30 @@
"integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
"license": "MIT"
},
+ "node_modules/fast-deep-equal": {
+ "version": "3.1.3",
+ "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+ "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/fast-uri": {
+ "version": "3.1.0",
+ "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
+ "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/fastify"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fastify"
+ }
+ ],
+ "license": "BSD-3-Clause"
+ },
"node_modules/fdir": {
"version": "6.5.0",
"resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -3383,6 +3833,16 @@
"node": "^8.16.0 || ^10.6.0 || >=11.0.0"
}
},
+ "node_modules/get-caller-file": {
+ "version": "2.0.5",
+ "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+ "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": "6.* || 8.* || >= 10.*"
+ }
+ },
"node_modules/get-east-asian-width": {
"version": "1.4.0",
"resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.4.0.tgz",
@@ -3994,6 +4454,20 @@
"js-yaml": "bin/js-yaml.js"
}
},
+ "node_modules/json-schema-traverse": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+ "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/jsonc-parser": {
+ "version": "2.3.1",
+ "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-2.3.1.tgz",
+ "integrity": "sha512-H8jvkz1O50L3dMZCsLqiuB2tA7muqbSg1AtGEkN0leAqGjsUzDJir3Zwr02BhqdcITPg3ei3mZ+HjMocAknhhg==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/kleur": {
"version": "3.0.3",
"resolved": "https://registry.npmjs.org/kleur/-/kleur-3.0.3.tgz",
@@ -5153,6 +5627,13 @@
"integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
"license": "MIT"
},
+ "node_modules/muggle-string": {
+ "version": "0.4.1",
+ "resolved": "https://registry.npmjs.org/muggle-string/-/muggle-string-0.4.1.tgz",
+ "integrity": "sha512-VNTrAak/KhO2i8dqqnqnAHOa3cYBwXEZe9h+D5h/1ZqFSTEFHdM65lR7RoIqq3tBBYavsOXV84NoHXZ0AkPyqQ==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/nanoid": {
"version": "3.3.11",
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
@@ -5381,6 +5862,13 @@
"url": "https://github.com/inikulin/parse5?sponsor=1"
}
},
+ "node_modules/path-browserify": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/path-browserify/-/path-browserify-1.0.1.tgz",
+ "integrity": "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/piccolore": {
"version": "0.1.3",
"resolved": "https://registry.npmjs.org/piccolore/-/piccolore-0.1.3.tgz",
@@ -5471,6 +5959,22 @@
"node": ">=4"
}
},
+ "node_modules/prettier": {
+ "version": "3.8.3",
+ "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.3.tgz",
+ "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==",
+ "dev": true,
+ "license": "MIT",
+ "bin": {
+ "prettier": "bin/prettier.cjs"
+ },
+ "engines": {
+ "node": ">=14"
+ },
+ "funding": {
+ "url": "https://github.com/prettier/prettier?sponsor=1"
+ }
+ },
"node_modules/prismjs": {
"version": "1.30.0",
"resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.30.0.tgz",
@@ -5823,6 +6327,33 @@
"url": "https://opencollective.com/unified"
}
},
+ "node_modules/request-light": {
+ "version": "0.7.0",
+ "resolved": "https://registry.npmjs.org/request-light/-/request-light-0.7.0.tgz",
+ "integrity": "sha512-lMbBMrDoxgsyO+yB3sDcrDuX85yYt7sS8BfQd11jtbW/z5ZWgLZRcEGLsLoYw7I0WSUGQBs8CC8ScIxkTX1+6Q==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/require-directory": {
+ "version": "2.1.1",
+ "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
+ "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/require-from-string": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+ "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
"node_modules/retext": {
"version": "9.0.0",
"resolved": "https://registry.npmjs.org/retext/-/retext-9.0.0.tgz",
@@ -6269,12 +6800,18 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
+ "node_modules/typesafe-path": {
+ "version": "0.2.2",
+ "resolved": "https://registry.npmjs.org/typesafe-path/-/typesafe-path-0.2.2.tgz",
+ "integrity": "sha512-OJabfkAg1WLZSqJAJ0Z6Sdt3utnbzr/jh+NAHoyWHJe8CMSy79Gm085094M9nvTPy22KzTVn5Zq5mbapCI/hPA==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/typescript": {
"version": "5.9.3",
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
"license": "Apache-2.0",
- "peer": true,
"bin": {
"tsc": "bin/tsc",
"tsserver": "bin/tsserver"
@@ -6283,6 +6820,16 @@
"node": ">=14.17"
}
},
+ "node_modules/typescript-auto-import-cache": {
+ "version": "0.3.6",
+ "resolved": "https://registry.npmjs.org/typescript-auto-import-cache/-/typescript-auto-import-cache-0.3.6.tgz",
+ "integrity": "sha512-RpuHXrknHdVdK7wv/8ug3Fr0WNsNi5l5aB8MYYuXhq2UH5lnEB1htJ1smhtD5VeCsGr2p8mUDtd83LCQDFVgjQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "semver": "^7.3.8"
+ }
+ },
"node_modules/ufo": {
"version": "1.6.3",
"resolved": "https://registry.npmjs.org/ufo/-/ufo-1.6.3.tgz",
@@ -6710,6 +7257,261 @@
}
}
},
+ "node_modules/volar-service-css": {
+ "version": "0.0.70",
+ "resolved": "https://registry.npmjs.org/volar-service-css/-/volar-service-css-0.0.70.tgz",
+ "integrity": "sha512-K1qyOvBpE3rzdAv3e4/6Rv5yizrYPy5R/ne3IWCAzLBuMO4qBMV3kSqWzj6KUVe6S0AnN6wxF7cRkiaKfYMYJw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "vscode-css-languageservice": "^6.3.0",
+ "vscode-languageserver-textdocument": "^1.0.11",
+ "vscode-uri": "^3.0.8"
+ },
+ "peerDependencies": {
+ "@volar/language-service": "~2.4.0"
+ },
+ "peerDependenciesMeta": {
+ "@volar/language-service": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/volar-service-emmet": {
+ "version": "0.0.70",
+ "resolved": "https://registry.npmjs.org/volar-service-emmet/-/volar-service-emmet-0.0.70.tgz",
+ "integrity": "sha512-xi5bC4m/VyE3zy/n2CXspKeDZs3qA41tHLTw275/7dNWM/RqE2z3BnDICQybHIVp/6G1iOQj5c1qXMgQC08TNg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@emmetio/css-parser": "^0.4.1",
+ "@emmetio/html-matcher": "^1.3.0",
+ "@vscode/emmet-helper": "^2.9.3",
+ "vscode-uri": "^3.0.8"
+ },
+ "peerDependencies": {
+ "@volar/language-service": "~2.4.0"
+ },
+ "peerDependenciesMeta": {
+ "@volar/language-service": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/volar-service-html": {
+ "version": "0.0.70",
+ "resolved": "https://registry.npmjs.org/volar-service-html/-/volar-service-html-0.0.70.tgz",
+ "integrity": "sha512-eR6vCgMdmYAo4n+gcT7DSyBQbwB8S3HZZvSagTf0sxNaD4WppMCFfpqWnkrlGStPKMZvMiejRRVmqsX9dYcTvQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "vscode-html-languageservice": "^5.3.0",
+ "vscode-languageserver-textdocument": "^1.0.11",
+ "vscode-uri": "^3.0.8"
+ },
+ "peerDependencies": {
+ "@volar/language-service": "~2.4.0"
+ },
+ "peerDependenciesMeta": {
+ "@volar/language-service": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/volar-service-prettier": {
+ "version": "0.0.70",
+ "resolved": "https://registry.npmjs.org/volar-service-prettier/-/volar-service-prettier-0.0.70.tgz",
+ "integrity": "sha512-Z6BCFSpGVCd8BPAsZ785Kce1BGlWd5ODqmqZGVuB14MJvrR4+CYz6cDy4F+igmE1gMifqfvMhdgT8Aud4M5ngg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "vscode-uri": "^3.0.8"
+ },
+ "peerDependencies": {
+ "@volar/language-service": "~2.4.0",
+ "prettier": "^2.2 || ^3.0"
+ },
+ "peerDependenciesMeta": {
+ "@volar/language-service": {
+ "optional": true
+ },
+ "prettier": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/volar-service-typescript": {
+ "version": "0.0.70",
+ "resolved": "https://registry.npmjs.org/volar-service-typescript/-/volar-service-typescript-0.0.70.tgz",
+ "integrity": "sha512-l46Bx4cokkUedTd74ojO5H/zqHZJ8SUuyZ0IB8JN4jfRqUM3bQFBHoOwlZCyZmOeO0A3RQNkMnFclxO4c++gsg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "path-browserify": "^1.0.1",
+ "semver": "^7.6.2",
+ "typescript-auto-import-cache": "^0.3.5",
+ "vscode-languageserver-textdocument": "^1.0.11",
+ "vscode-nls": "^5.2.0",
+ "vscode-uri": "^3.0.8"
+ },
+ "peerDependencies": {
+ "@volar/language-service": "~2.4.0"
+ },
+ "peerDependenciesMeta": {
+ "@volar/language-service": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/volar-service-typescript-twoslash-queries": {
+ "version": "0.0.70",
+ "resolved": "https://registry.npmjs.org/volar-service-typescript-twoslash-queries/-/volar-service-typescript-twoslash-queries-0.0.70.tgz",
+ "integrity": "sha512-IdD13Z9N2Bu8EM6CM0fDV1E69olEYGHDU25X51YXmq8Y0CmJ2LNj6gOiBJgpS5JGUqFzECVhMNBW7R0sPdRTMQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "vscode-uri": "^3.0.8"
+ },
+ "peerDependencies": {
+ "@volar/language-service": "~2.4.0"
+ },
+ "peerDependenciesMeta": {
+ "@volar/language-service": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/volar-service-yaml": {
+ "version": "0.0.70",
+ "resolved": "https://registry.npmjs.org/volar-service-yaml/-/volar-service-yaml-0.0.70.tgz",
+ "integrity": "sha512-0c8bXDBeoATF9F6iPIlOuYTuZAC4c+yi0siQo920u7eiBJk8oQmUmg9cDUbR4+Gl++bvGP4plj3fErbJuPqdcQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "vscode-uri": "^3.0.8",
+ "yaml-language-server": "~1.20.0"
+ },
+ "peerDependencies": {
+ "@volar/language-service": "~2.4.0"
+ },
+ "peerDependenciesMeta": {
+ "@volar/language-service": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/vscode-css-languageservice": {
+ "version": "6.3.10",
+ "resolved": "https://registry.npmjs.org/vscode-css-languageservice/-/vscode-css-languageservice-6.3.10.tgz",
+ "integrity": "sha512-eq5N9Er3fC4vA9zd9EFhyBG90wtCCuXgRSpAndaOgXMh1Wgep5lBgRIeDgjZBW9pa+332yC9+49cZMW8jcL3MA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@vscode/l10n": "^0.0.18",
+ "vscode-languageserver-textdocument": "^1.0.12",
+ "vscode-languageserver-types": "3.17.5",
+ "vscode-uri": "^3.1.0"
+ }
+ },
+ "node_modules/vscode-html-languageservice": {
+ "version": "5.6.2",
+ "resolved": "https://registry.npmjs.org/vscode-html-languageservice/-/vscode-html-languageservice-5.6.2.tgz",
+ "integrity": "sha512-ulCrSnFnfQ16YzvwnYUgEbUEl/ZG7u2eV27YhvLObSHKkb8fw1Z9cgsnUwjTEeDIdJDoTDTDpxuhQwoenoLNMg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@vscode/l10n": "^0.0.18",
+ "vscode-languageserver-textdocument": "^1.0.12",
+ "vscode-languageserver-types": "^3.17.5",
+ "vscode-uri": "^3.1.0"
+ }
+ },
+ "node_modules/vscode-json-languageservice": {
+ "version": "4.1.8",
+ "resolved": "https://registry.npmjs.org/vscode-json-languageservice/-/vscode-json-languageservice-4.1.8.tgz",
+ "integrity": "sha512-0vSpg6Xd9hfV+eZAaYN63xVVMOTmJ4GgHxXnkLCh+9RsQBkWKIghzLhW2B9ebfG+LQQg8uLtsQ2aUKjTgE+QOg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "jsonc-parser": "^3.0.0",
+ "vscode-languageserver-textdocument": "^1.0.1",
+ "vscode-languageserver-types": "^3.16.0",
+ "vscode-nls": "^5.0.0",
+ "vscode-uri": "^3.0.2"
+ },
+ "engines": {
+ "npm": ">=7.0.0"
+ }
+ },
+ "node_modules/vscode-json-languageservice/node_modules/jsonc-parser": {
+ "version": "3.3.1",
+ "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
+ "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/vscode-jsonrpc": {
+ "version": "8.2.0",
+ "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
+ "integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=14.0.0"
+ }
+ },
+ "node_modules/vscode-languageserver": {
+ "version": "9.0.1",
+ "resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz",
+ "integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "vscode-languageserver-protocol": "3.17.5"
+ },
+ "bin": {
+ "installServerIntoExtension": "bin/installServerIntoExtension"
+ }
+ },
+ "node_modules/vscode-languageserver-protocol": {
+ "version": "3.17.5",
+ "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
+ "integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "vscode-jsonrpc": "8.2.0",
+ "vscode-languageserver-types": "3.17.5"
+ }
+ },
+ "node_modules/vscode-languageserver-textdocument": {
+ "version": "1.0.12",
+ "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz",
+ "integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/vscode-languageserver-types": {
+ "version": "3.17.5",
+ "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
+ "integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/vscode-nls": {
+ "version": "5.2.0",
+ "resolved": "https://registry.npmjs.org/vscode-nls/-/vscode-nls-5.2.0.tgz",
+ "integrity": "sha512-RAaHx7B14ZU04EU31pT+rKz2/zSl7xMsfIZuo8pd+KZO6PXtQmpevpq3vxvWNcrGbdmhM/rr5Uw5Mz+NBfhVng==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/vscode-uri": {
+ "version": "3.1.0",
+ "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.1.0.tgz",
+ "integrity": "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/web-namespaces": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz",
@@ -6767,6 +7569,94 @@
"integrity": "sha512-147y/6YNh+tlp6nd/2pWq38i9h6mz/EuQ6njIrmW8D1BS5nCqs0P6DG+m6zTGnNz5I+uhZ0SHxBs9BsPrwcKDA==",
"license": "MIT"
},
+ "node_modules/y18n": {
+ "version": "5.0.8",
+ "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+ "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/yaml": {
+ "version": "2.8.3",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz",
+ "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==",
+ "devOptional": true,
+ "license": "ISC",
+ "bin": {
+ "yaml": "bin.mjs"
+ },
+ "engines": {
+ "node": ">= 14.6"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/eemeli"
+ }
+ },
+ "node_modules/yaml-language-server": {
+ "version": "1.20.0",
+ "resolved": "https://registry.npmjs.org/yaml-language-server/-/yaml-language-server-1.20.0.tgz",
+ "integrity": "sha512-qhjK/bzSRZ6HtTvgeFvjNPJGWdZ0+x5NREV/9XZWFjIGezew2b4r5JPy66IfOhd5OA7KeFwk1JfmEbnTvev0cA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@vscode/l10n": "^0.0.18",
+ "ajv": "^8.17.1",
+ "ajv-draft-04": "^1.0.0",
+ "prettier": "^3.5.0",
+ "request-light": "^0.5.7",
+ "vscode-json-languageservice": "4.1.8",
+ "vscode-languageserver": "^9.0.0",
+ "vscode-languageserver-textdocument": "^1.0.1",
+ "vscode-languageserver-types": "^3.16.0",
+ "vscode-uri": "^3.0.2",
+ "yaml": "2.7.1"
+ },
+ "bin": {
+ "yaml-language-server": "bin/yaml-language-server"
+ }
+ },
+ "node_modules/yaml-language-server/node_modules/request-light": {
+ "version": "0.5.8",
+ "resolved": "https://registry.npmjs.org/request-light/-/request-light-0.5.8.tgz",
+ "integrity": "sha512-3Zjgh+8b5fhRJBQZoy+zbVKpAQGLyka0MPgW3zruTF4dFFJ8Fqcfu9YsAvi/rvdcaTeWG3MkbZv4WKxAn/84Lg==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/yaml-language-server/node_modules/yaml": {
+ "version": "2.7.1",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.7.1.tgz",
+ "integrity": "sha512-10ULxpnOCQXxJvBgxsn9ptjq6uviG/htZKk9veJGhlqn3w/DxQ631zFF+nlQXLwmImeS5amR2dl2U8sg6U9jsQ==",
+ "dev": true,
+ "license": "ISC",
+ "bin": {
+ "yaml": "bin.mjs"
+ },
+ "engines": {
+ "node": ">= 14"
+ }
+ },
+ "node_modules/yargs": {
+ "version": "17.7.2",
+ "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
+ "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "cliui": "^8.0.1",
+ "escalade": "^3.1.1",
+ "get-caller-file": "^2.0.5",
+ "require-directory": "^2.1.1",
+ "string-width": "^4.2.3",
+ "y18n": "^5.0.5",
+ "yargs-parser": "^21.1.1"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
"node_modules/yargs-parser": {
"version": "21.1.1",
"resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
@@ -6776,6 +7666,51 @@
"node": ">=12"
}
},
+ "node_modules/yargs/node_modules/ansi-regex": {
+ "version": "5.0.1",
+ "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+ "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/yargs/node_modules/emoji-regex": {
+ "version": "8.0.0",
+ "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+ "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/yargs/node_modules/string-width": {
+ "version": "4.2.3",
+ "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+ "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "emoji-regex": "^8.0.0",
+ "is-fullwidth-code-point": "^3.0.0",
+ "strip-ansi": "^6.0.1"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/yargs/node_modules/strip-ansi": {
+ "version": "6.0.1",
+ "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+ "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "ansi-regex": "^5.0.1"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
"node_modules/yocto-queue": {
"version": "1.2.2",
"resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-1.2.2.tgz",
diff --git a/website/package.json b/website/package.json
index 32285bc..b764863 100644
--- a/website/package.json
+++ b/website/package.json
@@ -19,6 +19,8 @@
"sharp": "^0.33.5"
},
"devDependencies": {
- "@types/node": "^22.10.5"
+ "@astrojs/check": "^0.9.8",
+ "@types/node": "^22.10.5",
+ "typescript": "^5.9.3"
}
}