ai-developer-skill-os 8.1.4 → 8.1.7

package/.agents/CHANGELOG.md

@@ -1,70 +1,113 @@
-# Changelog
-
-All notable changes to the **AI Developer Skill OS** project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [7.0.2] - 2026-07-15
-
-### Added
-- **Frontend Integration**: Added `qk-fe-api-integration` skill to strictly enforce zero-overhead base API consumption, DTO mapping, and resilient UI states.
-
-## [7.0.0] - 2026-07-15
-
-### Changed (The "Anti-Slop & Zero-Trust" Architecture Upgrade)
-- **Zero-Trust Logic**: Core logic skills (`qk-context-loader`, `qk-orchestrator`, `qk-feature-delivery`) now mandate a Topological Context Graph prior to any code generation.
-- **Strict Design Contract**: Frontend skills (`qk-ui-system-builder`, `qk-ui-builder`, `qk-ui-audit`) now explicitly reject generic styling (slop) and enforce strict token matching against a mandated `DESIGN.md`.
-- **Repair Loop Enforcement**: `qk-bug-resolution` updated to strictly prohibit jumping to fixes without explicitly establishing an `Observe -> Hypothesis -> Evidence` chain.
-- **Contract-First APIs**: `qk-api-lifecycle` now requires explicit OpenAPI/Swagger definitions prior to endpoint implementation.
-- **Upgraded Testing Framework**: Fixed regex and validation logic in `behavior-conformance.test.js` to rigorously support YAML array strings and precise V7 markdown constraints. All 22 skills bumped to `v7.0.0`.
-- **Project Bootstrapping**: `qk-project-bootstrap` now scaffolds `DESIGN.md` explicitly upon initialization.
-
-
-## [4.0.0] - 2026-07-02
-
-### Changed (Major Architecture Upgrade)
-- **Intent-Based Agent Architecture:** Replaced rule-based individual skill exceptions with global behavioral group classifications (Static Analysis, Development, Validation, Maintenance).
-- **OS Kernel Refactor:** Completely rewrote `AGENTS.md` (the "OS Kernel") into a strictly organized, lightweight structure under 100 lines.
-- **Progressive Evidence Collection:** Agents now enforce an 80% Confidence Threshold and incremental Context Budget (`1 file` → `3 files`) to prevent over-fetching and hallucination loops.
-- **Cost & Escalation Policies:** Introduced strict cost-optimization logic, Stopping Criteria, and Escalation protocols to prevent infinite `run_command` retries.
-- **Risk-based Verification:** Dynamic test execution based on the risk level of changes (Levels 0-3).
-
-### Added
-- **Registry Validation Suite:** Full Vitest test suite enforcing SKILL.md frontmatter compliance against `docs/SPEC.md`.
-- **GitHub Actions CI:** Automated validation on every PR and push to main.
-- **Idempotent Installer:** `bin/install.js` now detects and updates existing rule blocks instead of duplicating them.
-- **Kilo Code Native Support:** First-class support for `CLAUDE.md` + `kilo.json` config generation.
-- **Governance Docs:** `docs/GOVERNANCE.md`, ADRs, and skill classification policy for enterprise maintainability.
-- **Engineering Standards:** `qk-engineering-standard` and `qk-validation-gate` skills enforce SOLID, DRY, Clean Code, and mandatory quality gates.
-
-## [1.0.1] - 2026-07-01
-### Fixed
-- Standardized Language rule across all 23 SKILL.md files for consistency.
-- Updated registry version to match package.json.
-
-## [1.0.0] - 2026-07-01
-
-### Added
-- Released the complete AI Developer Skill OS with 23 targeted skills for coding agents.
-- **Engineering Core (8 skills):**
-  - `agent-orchestrator` for planning and delegating tasks.
-  - `context-manager` for project context and file selection.
-  - `project-audit` for 3-mode health checks.
-  - `bug-fix` with root cause analysis.
-  - `refactor` for safe, behavior-preserving code restructuring.
-  - `migration` for dependency updates and library swapping.
-  - `api-integration` for robust API connections.
-  - `git-engineer` for commit messages and PR documentation.
-- **Frontend Core (11 skills):**
-  - `frontend-architecture`, `design-system`, `ui-builder`, `component-generator`.
-  - `state-management`, `form-builder`, `table-crud-generator`.
-  - `frontend-debug`, `frontend-testing`, `accessibility-audit`, `frontend-performance`.
-- **Backend Core (4 skills):**
-  - `backend-architecture`, `database-engineer`, `auth-security`, `deployment`.
-- Added comprehensive `skills.json` registry with dependencies and trigger keywords.
-- Added bilingual `README.md` (English/Vietnamese).
-- Added detailed user documentation in `docs/HUONG_DAN_SU_DUNG.md` and `docs/CHI_TIET_SKILLS.md`.
-- Translated all skill frontmatter descriptions to Vietnamese for better UX in agent terminals.
-- Included generic English and Vietnamese usage examples in `_template/examples/`.
-
+# Changelog
+
+All notable changes to AI Developer Skill OS are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+
+---
+
+## [8.1.7] — 2026-07 — README Sync
+
+### Changed
+- **README Sync**: Synced `.agents/README.md` with root `README.md` so the installed documentation is fully up-to-date with V8.1 architecture.
+- Bumped version to `8.1.7`.
+
+---
+
+## [8.1.6] — 2026-07 — Design Intelligence Content & Sync
+
+### Added
+- **Design Intelligence Populated**: Sourced core market-standard knowledge (Tailwind, Radix, Apple, Vercel-like principles) into `.agents/knowledge/design-intelligence/` covering components, patterns, industries, themes, and references.
+- **Animation Knowledge**: Added `visual-language/animation.md` for micro-interactions and transition durations.
+- **Dependency Wiring**: Linked `qk-ui-system-builder` to `design-intelligence` so it utilizes the newly generated design constraints.
+- **Changelog Sync**: Synced `.agents/CHANGELOG.md` with root `CHANGELOG.md` so the installed copy reflects the true V8 evolution.
+
+### Changed
+- All skill descriptions properly translated to Vietnamese for ecosystem consistency.
+- Bumped version to `8.1.6` for final, truly complete Design Intelligence NPM Release.
+
+---
+
+## [8.1.4] — 2026-07 — Design Intelligence Pack
+
+### Added
+- **Design Intelligence Layer**: `.agents/knowledge/design-intelligence/` (industries, themes, patterns, visual-language, components, templates)
+- **Knowledge Dependencies**: `qk-design-system-engineering` and `qk-ui-builder` now have strict dependency bounds tied to Design Intelligence without bloating the Capability Graph.
+- **Design Routing Test Cases**: `design-intel-01`, `02`, `03` for validating routing logic in design scenarios.
+- **Re-introduced CLI Installer**: Restored and refactored `bin/install.js` to correctly copy `.agents` across global/local directories for easy NPM setup.
+
+### Changed
+- Refined **Decision Boundaries**: `qk-ui-builder` explicitly forbidden from defining visual direction or brand identity (strict capability bounds).
+- **README.md** reflects 30 Master Skills and the "Agent Engineering OS" mindset.
+- **package.json**: Version bump `8.1.4` and whitelisted files for npm publish.
+
+---
+
+## [8.1.3] — 2026-07 — Architecture Freeze & Governance
+
+### Added
+- **Capability Graph & Routing**: `.agents/registry/capability-graph.yml` to define skill relations (`depends_on`, `delegates_to`).
+- **Priority Governance**: `.agents/rules/priorities.yml` enforcing safety layers (`P1: System Integrity`, `P2: Guardrails`).
+- **Audit Tools**: `tooling/run-aar.js` for architectural acceptance testing.
+- Test cases for routing and boundary attacks.
+
+### Changed
+- Name transition from "Self-Improving" to **Adaptive Agent OS** (Self Optimizing ≠ Self Modifying).
+- Enforced hard cap of **30 Skills** to prevent Skill Inflation.
+- Frozen Baseline achieved: `v8.1.3-agent-os-production`.
+
+---
+
+## [8.0.0] — 2026-07 — Agent Knowledge System
+
+### Philosophy shift
+- **V7:** Skill Repository — human selects skill, AI executes
+- **V8:** Agent Knowledge System — AI retrieves context, selects capability, executes workflow, verifies
+
+### Added
+- `rules/` — Agent behavior policies (global, coding, safety)
+- `workflows/` — Reusable execution pipelines (YAML, with inputs/outputs per step)
+- `examples/` — Few-shot knowledge (good/, bad/)
+- `learnings/` — Evidence-based learning lifecycle (draft/, validated/, deprecated/)
+- `registry/` — Generated AI retrieval index (skills-index.yml)
+- `docs/ARCHITECTURE.md` — Agent request flow diagram
+- `docs/VERSIONING.md` — Semantic versioning policy
+- `docs/schemas/` — Schema definitions for all knowledge objects
+- `docs/decisions/` — Architecture Decision Records (ADRs)
+- `.agentsignore` — AI boundary file (what agents should NOT load)
+- `tooling/` — Dev automation (generate-registry.js, validate-skills.js)
+- `tests/agent-evaluation/` — Agent behavior test harness
+
+### Changed
+- SKILL.md schema upgraded to V8: added `type`, `intent`, `triggers`, `complexity`, `workflow`, `verification`, `related_skills`
+- `skills.json` demoted to **generated compatibility manifest** (source of truth = SKILL.md)
+- Workflows extracted from individual skills → shared reusable templates
+
+### Removed
+- Embedded workflows inside SKILL.md body (moved to workflows/)
+- Old migration scripts (migrate-v*.js, patch*.py, add_lang.*, etc.)
+- Duplicate documentation (CLAUDE.md, old docs/)
+- Experimental packages (packages/edaos-sdk)
+- framework/, knowledge/, specs/, templates/ directories
+
+### Migration
+- V7.5.1 tagged at git: `v7.5.1`
+- V7 skills preserved in git history; migration is additive schema upgrade
+
+---
+
+## [7.5.1] — 2026-07 — Final V7 Release
+
+- Bumped all skill versions to 7.5.1
+- Added qk-fe-api-integration skill
+- Added qk-performance-tuner (global config)
+- Stabilized frontmatter schema across all 22 skills
+
+## [7.5.0] — 2026-07
+
+- Major skills refactor with EDAOS runtime adapter
+- Added MCP server integration
+- Added qk-bug-resolution workflow contracts
+
+## [7.0.0] — 2026
+
+- V7 release: 22 skills, YAML frontmatter, token budget system

package/.agents/README.md

@@ -1,74 +1,52 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v7.5.0
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v8.1.4
 
-> **V7.5.0 "Anti-Slop & Zero-Trust Architecture"**
+> **v8.1.4 "Agent Engineering OS + Design Intelligence"**
 
-Hệ sinh thái AI Developer Skill OS đã được tái cấu trúc hoàn toàn. Thay vì cung cấp các "công cụ rời rạc" (Toolbox), phiên bản V7 được thiết kế như một **Hệ điều hành khép kín, hoạt động theo kỷ luật của một Kiến trúc sư Hệ thống (50 năm kinh nghiệm)**.
+Hệ sinh thái AI Developer Skill OS đã lột xác hoàn toàn. Từ một bộ "công cụ phân tán" (Toolbox) ở V7, phiên bản V8.1.4 được thiết kế như một **Hệ điều hành khép kín (Agent Engineering OS)**, sở hữu năng lực giám sát, bảo vệ ranh giới quyết định (Decision Boundaries) và được trang bị thêm tầng **Design Intelligence**.
 
 ---
 
-## 🏗️ Triết Lý Hoạt Động Cốt Lõi (V7 Kernel)
+## 🏗️ Triết Lý Hoạt Động Cốt Lõi (V8 Kernel)
 
-### 1. Zero-Trust Context (Không bao giờ đoán mò)
-Mọi kỹ năng phân tích logic và backend (như `qk-feature-delivery`, `qk-orchestrator`) đều bị khoá chặt, không được phép hoạt động nếu chưa có **Dependency Graph** (Bản đồ cấu trúc) từ `qk-context-loader`. AI không được phép thay đổi code dựa trên trí tưởng tượng.
+### 1. Decision Boundary (Ranh giới Thẩm quyền)
+Không còn tình trạng một Skill ôm đồm mọi việc. Mọi Skill (Kỹ năng) hiện tại bị quản lý bởi các trường `owns`, `does_not_own`, `conflicts_with`, `delegates_to`. Thợ code UI (`qk-ui-builder`) không được phép tự ra quyết định kiến trúc, và ngược lại.
 
-### 2. Contract-First (Khế ước đi đầu)
-- **Frontend / UI**: Mọi sửa đổi giao diện đều phải dựa trên `DESIGN.md`. Nếu vi phạm (tạo ra giao diện lười biếng "slop", dùng màu mặc định sai lệch), AI sẽ tự động bị đánh trượt bài kiểm toán.
-- **Backend / API**: Mọi API phải được viết `OpenAPI/Swagger` schema trước khi viết logic thực tế (`qk-api-lifecycle`).
-- **Database**: Cấm truy vấn mù. Bắt buộc phải có Schema định nghĩa rõ ràng trước (`qk-data-lifecycle`).
+### 2. Design Intelligence Layer
+Khắc phục điểm yếu "mù thẩm mỹ" của AI. Agent giờ đây không chỉ biết code mà còn có Gu Thẩm Mỹ (Design Taste). Dựa trên yêu cầu của bạn, hệ thống tự động tra cứu **Knowledge Graph** để chọn đúng Theme (Fintech, Healthcare, SaaS...), Typography và Visual Patterns trước khi giao việc cho UI Builder.
 
-### 3. Repair Loop (Chu trình Sửa Lỗi Khép Kín)
-Bảo vệ mã nguồn khỏi thói quen "sửa vội" của AI. Lỗi bắt buộc phải qua chu trình điều tra nghiêm ngặt: `Observe -> Hypothesis -> Evidence -> Fix -> Verify` (`qk-bug-resolution`).
+### 3. Khế Ước Đi Đầu (Contract-First & Zero-Trust)
+- **Frontend / UI**: Mọi sửa đổi phải tuân thủ Design System (được `qk-design-system-engineering` kiểm duyệt).
+- **Backend / API**: Phải viết OpenAPI/Swagger contract trước (`qk-api-lifecycle`).
+- **Data**: Cấm AI tự đoán cấu trúc DB, mọi truy vấn phải có Schema (`qk-data-lifecycle`).
 
 ---
 
-## 🧩 Danh sách 22 Master Skills
+## 🧩 Danh sách 30 Master Skills
 
-Các kỹ năng được quản lý cực kỳ chặt chẽ với bài kiểm tra tự động (Vitest) để đảm bảo tính nhất quán của luật lệ:
-- **Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-access-policy`
-- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-fe-api-integration`, `qk-data-lifecycle`, `qk-ui-builder`, `qk-ui-system-builder`
-- **Validation & Standards:** `qk-validation-gate`, `qk-engineering-standard`, `qk-ui-audit`, `qk-project-health`, `qk-bug-resolution`
-- **Ops & AI:** `qk-system-evolution`, `qk-production-release`, `qk-ai-builder`, `qk-project-bootstrap`
-- **Docs & Utils:** `qk-docs`, `qk-project-memory`, `qk-help`, `qk-db-optimizer`
+Các kỹ năng được quản lý bằng **Capability Graph** và được đánh giá liên tục thông qua Evaluation Suite. Bao gồm 7 lĩnh vực:
+1. **Core & Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-project-memory`, `qk-help`
+2. **Product & Architecture:** `qk-product-specification`, `qk-project-bootstrap`, `qk-frontend-architecture`
+3. **Frontend & UI:** `qk-design-system-engineering`, `qk-ui-system-builder`, `qk-ui-builder`, `qk-fe-api-integration`, `qk-ui-audit`
+4. **Backend & Data:** `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-access-policy`
+5. **Engineering & Delivery:** `qk-feature-delivery`, `qk-bug-resolution`, `qk-engineering-standard`, `qk-system-evolution`, `qk-docs`
+6. **Quality & Testing:** `qk-test-engineering`, `qk-validation-gate`, `qk-web-quality-gate`, `qk-project-health`
+7. **Security, DevOps & Analytics:** `qk-security-audit`, `qk-db-optimizer`, `qk-devops-platform`, `qk-production-release`, `qk-agent-observability`, `qk-ai-builder`
 
 ---
 
 ## 💻 Cách Cài Đặt (Installation)
 
-### Cách 1: NPM Global (Khuyên dùng cho nhiều máy)
+### Cách 1: NXP (Không cần cài global) - MỚI
 ```bash
-npm i -g ai-developer-skill-os
+npx ai-developer-skill-os init
 ```
 
-### Cách 2: NXP (Không cần cài global)
+### Cách 2: NPM Global (Khuyên dùng cho cá nhân)
 ```bash
-npx ai-developer-skill-os init --ide=antigravity --scope=2
-```
-
-### Cách 3: NPM Scripts (Trong dự án)
-```bash
-# Antigravity Global — 1 lần cài, mọi dự án dùng chung
-npm run install:antigravity
-
-# Antigravity Local — cài riêng cho dự án này
-npm run install:antigravity:local
-
-# Các IDE khác
-npm run install:cursor        # Global Cursor
-npm run install:windsurf      # Global Windsurf
-npm run install:claude        # Global Claude Code
-npm run install:kilo          # Global Kilo Code
-npm run install:multi         # Multi-IDE
+npm i -g ai-developer-skill-os
 ```
 
-## 📦 Tham số cho `init`
-
-| Tham số | Giá trị | Mô tả |
-|---------|---------|-------|
-| `--ide` | `antigravity`, `cursor`, `windsurf`, `claude`, `kilo`, `multi-ide` | IDE/AI Assistant |
-| `--scope` | `1` = Local, `2` = Global | Phạm vi cài đặt |
-
-### Ví dụ thực tế
-
+### Chạy bằng tham số (Command Line Arguments)
 ```bash
 # Cài Antigravity Global (toàn máy)
 npx ai-developer-skill-os init --ide=antigravity --scope=2
@@ -78,23 +56,31 @@ npx ai-developer-skill-os init --ide=antigravity --scope=1
 
 # Cài Cursor Local
 npx ai-developer-skill-os init --ide=cursor --scope=1
-
-# Cài Multi-IDE (tạo CLAUDE.md + .qk-ai-skill-os)
-npx ai-developer-skill-os init --ide=multi-ide --scope=2
 ```
 
-## 🧪 Testing
+## 📦 Các IDE/AI Assistant Được Hỗ Trợ
+- (1) Cursor
+- (2) Windsurf
+- (3) Cline / Roo Code
+- (4) Antigravity / Gemini
+- (5) Codex
+- (6) Kilo Code
 
-Hệ thống được bảo vệ bằng bộ Test Suite (Vitest) để tự động kiểm toán tính hợp lệ của toàn bộ 22 file Kỹ năng trước khi xuất bản:
+---
+
+## 🧪 Đánh Giá Tự Động (Agent Evaluation)
+
+Hệ thống đi kèm một bộ Runner nội bộ để kiểm toán **Routing Intelligence**. Bất kỳ cập nhật nào vào hệ thống Kỹ năng đều phải vượt qua bài kiểm tra hóc búa (Bypass Security, Boundary Attacks, Ambiguous Prompts):
 
 ```bash
-npm test
+npm run test:agent
+npm run test:graph
+npm run test:registry
 ```
 
-## 🚀 Tra Cứu (Help)
-
-Để tra cứu danh sách các Kỹ năng và luật lệ khắt khe của hệ thống V7, hãy gọi:
+## 🚀 Hướng Dẫn Sử Dụng
+Sau khi cài đặt thành công, hãy gõ lệnh:
 ```bash
 ./qk-help
 ```
-
+để kích hoạt AI Orchestrator và khám phá sức mạnh của hệ điều hành!

package/.agents/knowledge/design-intelligence/components/buttons.md

@@ -0,0 +1,25 @@
+# Buttons (Nút bấm) Intelligence
+
+Nút bấm là thành phần tương tác quan trọng nhất. Phải luôn tuân thủ phân cấp và trạng thái.
+
+## 1. Phân cấp thị giác (Hierarchy)
+- **Primary Button**: Nổi bật nhất (Background màu nhấn, Text trắng). Chỉ có 1 nút Primary trên một khu vực/màn hình.
+  - *Tailwind: `bg-blue-600 text-white hover:bg-blue-700`*
+- **Secondary / Default Button**: Nền nhạt hoặc xám, chữ đen/xám. Dành cho các hành động phụ (Hủy, Quay lại).
+  - *Tailwind: `bg-slate-100 text-slate-900 hover:bg-slate-200`*
+- **Outline Button**: Viền màu, nền trong suốt. Thường dùng thay thế Secondary.
+  - *Tailwind: `border border-slate-300 text-slate-700 hover:bg-slate-50`*
+- **Ghost / Text Button**: Không nền, không viền, chỉ hiện nền khi hover. Dùng cho hành động ít quan trọng.
+  - *Tailwind: `text-slate-600 hover:bg-slate-100 hover:text-slate-900`*
+
+## 2. Trạng thái (States) - BẮT BUỘC
+- **Hover**: Thay đổi sắc thái màu (đậm hơn hoặc nhạt hơn), thay đổi shadow.
+- **Focus / Focus-visible**: Vô cùng quan trọng cho Accessibility (Bàn phím). Phải có Focus Ring mờ.
+  - *Tailwind: `focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2`*
+- **Disabled**: Nền xám mờ, mờ chữ (`opacity-50`), con trỏ không cho phép (`cursor-not-allowed`).
+- **Loading**: Bắt buộc khóa nút (`disabled`) và thay icon bằng Spinner xoay tròn.
+
+## 3. Kích thước chuẩn
+- **Size sm**: Chiều cao 32px (`h-8 px-3 text-sm`).
+- **Size md (Base)**: Chiều cao 40px (`h-10 px-4 text-sm font-medium`).
+- **Size lg**: Chiều cao 48px (`h-12 px-6 text-base`).

package/.agents/knowledge/design-intelligence/components/cards.md

@@ -0,0 +1,21 @@
+# Cards (Thẻ thông tin) Intelligence
+
+Card là đơn vị chứa (container) linh hoạt nhất để nhóm các thông tin liên quan.
+
+## 1. Cấu trúc chuẩn (Anatomy)
+- **Header**: Icon, Hình ảnh (Cover image), hoặc Tiêu đề + Badge.
+- **Body**: Tiêu đề chính, đoạn văn mô tả ngắn (thường truncate 2-3 dòng).
+- **Footer**: Nút hành động (CTA), thông tin Metadata (Thời gian, tác giả).
+- Khoảng cách (Padding) trong Card phải đồng nhất (ví dụ: `p-5` hoặc `p-6` cho mọi phía).
+
+## 2. Borders & Shadows (Viền & Đổ bóng)
+Có hai trường phái chính, không nên trộn lẫn lộn xộn trong cùng 1 project:
+- **Trường phái Flat (SaaS/Modern)**: Không bóng, viền mỏng. 
+  - *Tailwind: `bg-white border border-slate-200 rounded-xl`*
+- **Trường phái Elevated (App/Ecom)**: Không viền, đổ bóng đa lớp.
+  - *Tailwind: `bg-white shadow-sm hover:shadow-md transition-shadow rounded-xl`*
+
+## 3. Trạng thái tương tác (Interactive Cards)
+Nếu toàn bộ Card có thể click (Vd: Link tới bài viết, Sản phẩm):
+- Khi hover: Bóng đổ lớn hơn một chút (`hover:shadow-md`), viền đổi màu (`hover:border-blue-500`), hoặc nhích nhẹ card lên trên (`hover:-translate-y-1 transition-transform`).
+- Con trỏ phải là bàn tay (`cursor-pointer`).

package/.agents/knowledge/design-intelligence/components/inputs.md

@@ -0,0 +1,14 @@
+# Inputs (Trường nhập liệu) Intelligence
+
+## 1. Cấu trúc Input 
+- Input phải có chiều cao tương ứng với Button (sm: 32px, md: 40px, lg: 48px).
+- Nền trắng (`bg-white`), viền nhạt (`border-slate-300`), chữ đen nhạt (`text-slate-900`).
+- Trạng thái Focus: Viền đổi sang màu Primary và có tỏa bóng nhẹ. (Tailwind: `focus:border-blue-500 focus:ring-1 focus:ring-blue-500`).
+
+## 2. Placeholder
+- Không dùng Placeholder để thay thế cho Label.
+- Chữ Placeholder phải mờ (`text-slate-400`) để không bị nhầm là đã nhập liệu.
+
+## 3. Cấu trúc phức tạp
+- Input có Icon bên trái (Search) hoặc bên phải (Show Password). Icon phải cùng màu với Placeholder.
+- Input Group (Có tiền tố, vd: "https://", hoặc hậu tố ".com") cần nền xám nhạt cho phần tiền tố.

package/.agents/knowledge/design-intelligence/components/modals.md

@@ -0,0 +1,14 @@
+# Modals / Dialogs Intelligence
+
+## 1. Lớp phủ (Overlay/Backdrop)
+- Sử dụng nền đen mờ (`bg-black/50`) hoặc làm mờ nhẹ đằng sau (`backdrop-blur-sm`) để khóa sự chú ý vào Modal.
+
+## 2. Cấu trúc Modal
+- **Header**: Tiêu đề rõ ràng, bắt buộc có nút "X" (Đóng) ở góc trên cùng bên phải.
+- **Body**: Nội dung chính, không nên để Modal quá cao gây cuộn màn hình. (Nên max-height `max-h-[80vh]` và `overflow-y-auto`).
+- **Footer**: Nút hành động. Nút Primary luôn nằm bên phải, nút Hủy (Cancel) nằm bên trái.
+
+## 3. Hành vi
+- Bấm vào Overlay (bên ngoài Modal) thì Modal phải đóng lại.
+- Bấm phím `Escape` thì Modal phải đóng lại.
+- Focus phải bị khóa (Trap focus) bên trong Modal khi đang mở.

package/.agents/knowledge/design-intelligence/industries/ecommerce.md

@@ -1,3 +1,16 @@
 # E-commerce Design Intelligence
 
-Focus: Conversion-optimized, high visual hierarchy, vibrant.
+## 1. Core Principles
+- **Conversion-Optimized**: Mục tiêu tối thượng là tăng tỉ lệ chuyển đổi (Click to Cart, Checkout).
+- **Visual Hierarchy**: Hình ảnh sản phẩm là vua, nút "Mua hàng" phải là thứ nổi bật nhất màn hình.
+- **Scarcity & Urgency**: Sử dụng các pattern như đếm ngược, số lượng còn lại, đánh giá (Reviews).
+
+## 2. Visual Language
+- **Màu sắc**: Màu nhấn (Brand color) hoặc các màu kích thích hành động (Cam/Đỏ/Đen tuyền). Các nút phụ (Thêm vào wishlist) phải mờ nhạt hẳn so với nút Mua.
+- **Typography**: Giá tiền thường dùng font weight đậm, giá khuyến mãi đi kèm giá gốc bị gạch ngang.
+- **Hình ảnh**: Product card cần aspectRatio vuông (1:1) hoặc chữ nhật (4:5) có nền trắng/xám đồng nhất.
+
+## 3. Component Patterns
+- **Product Card**: Chứa Ảnh (có tag Giảm giá nổi bật), Tên sản phẩm (truncate 2 dòng), Đánh giá (Số sao vàng), Giá tiền, và nút Add to Cart dạng Icon hoặc Full Width.
+- **Sticky CTA**: Trên Mobile, nút Mua/Thanh toán thường ghim chặt (Sticky) ở cạnh dưới màn hình.
+- **Badges**: Các tem "Bán chạy", "Freeship", "Mới" dùng màu sắc sặc sỡ, font size rất nhỏ (`text-[10px]` hoặc `text-xs` uppercase font-bold).

package/.agents/knowledge/design-intelligence/industries/fintech.md

@@ -1,3 +1,16 @@
 # Fintech Design Intelligence
 
-Focus: Trustworthy, data-heavy, clean, secure.
+## 1. Core Principles
+- **Trust & Security**: Giao diện phải mang lại cảm giác an toàn tuyệt đối.
+- **Data Density**: Hiển thị nhiều dữ liệu (bảng biểu, số liệu) nhưng không lộn xộn.
+- **Precision**: Các con số tiền tệ cần căn lề phải (right-aligned) và sử dụng tabular numbers (Tailwind: `tabular-nums`) để không bị giật khi số thay đổi.
+
+## 2. Visual Language
+- **Màu sắc**: Xanh dương (Blue/Indigo) tạo sự chuyên nghiệp và tin cậy; Xanh lá (Emerald) cho lợi nhuận/thành công; Đỏ (Rose) cho thua lỗ/chi tiêu.
+- **Typography**: Phông chữ gọn gàng, rõ ràng (Inter, Roboto). Chú ý đặc biệt đến trọng lượng chữ cho các con số tổng tiền (Balance) thường dùng `font-semibold` hoặc `font-bold`, kích thước lớn.
+- **Bảng (Tables)**: Không viền dọc, chỉ dùng viền ngang (horizontal dividers) nhạt (`border-slate-100`) với padding rộng rãi để dễ dò hàng.
+
+## 3. Component Patterns
+- **Cards**: Ít dùng shadow lớn. Thường dùng border 1px nhạt (`border border-slate-200`) hoặc shadow cực mỏng (`shadow-sm`).
+- **Data Visualization**: Biểu đồ (Sparklines) đơn giản, dùng gradient mờ ảo.
+- **Empty States**: Rất quan trọng để hướng dẫn người dùng liên kết thẻ, nạp tiền.

package/.agents/knowledge/design-intelligence/industries/healthcare.md

@@ -1,3 +1,16 @@
 # Healthcare Design Intelligence
 
-Focus: Accessible, calming, reliable, clear hierarchy.
+## 1. Core Principles
+- **Accessibility First**: Tương phản cao, chữ lớn dễ đọc, phục vụ đối tượng lớn tuổi hoặc thị lực kém.
+- **Calm & Empathy**: Giảm thiểu lo âu bằng khoảng trắng (white-space) nhiều, màu sắc dịu.
+- **Clarity**: Không dùng các từ lóng hay thuật ngữ khó hiểu, luồng đi (User Flow) phải cực kỳ tuyến tính.
+
+## 2. Visual Language
+- **Màu sắc**: Trắng, Xanh biển nhạt (Light Blue), Xanh bạc hà (Teal), mang lại cảm giác vệ sinh, y khoa. Tránh dùng màu đỏ gắt trừ trường hợp cấp cứu (Emergency).
+- **Typography**: System fonts hoặc các font có nét chữ dễ nhận diện (chữ l và chữ I không bị nhầm lẫn).
+- **Spacing**: Tăng padding/margin lên 1 cấp so với bình thường. Các nút bấm (Touch targets) phải lớn hơn (tối thiểu 44x44px theo chuẩn Apple) để người lớn tuổi dễ bấm.
+
+## 3. Component Patterns
+- **Forms**: Rõ ràng, nhãn (Label) luôn nằm trên Input (Top-aligned) thay vì nằm bên trái. Bắt buộc có thông báo lỗi cực kỳ dễ hiểu.
+- **Progress Bars**: Sử dụng cho các form đăng ký khám bệnh dài.
+- **Status Badges**: Dùng để hiển thị trạng thái hồ sơ/lịch hẹn (Chờ khám, Đã xác nhận) với màu sắc Pastel.

package/.agents/knowledge/design-intelligence/patterns/data-display.md

@@ -0,0 +1,18 @@
+# Data Display Patterns
+
+## 1. Tables (Bảng dữ liệu)
+- **Thiết kế**: Dùng cho dữ liệu có cấu trúc. Bỏ viền dọc, giữ viền ngang nhạt (`border-b border-slate-200`).
+- **Căn lề**: 
+  - Text: Trái (Left).
+  - Số lượng, Tiền tệ: Phải (Right).
+  - Trạng thái (Status): Giữa hoặc Trái (Dùng Badge/Tag).
+- **Phản hồi**: Hover vào từng hàng (`hover:bg-slate-50`) để người dùng không nhìn nhầm dòng.
+
+## 2. Lists & Feeds (Danh sách)
+- Thay vì dùng Card, các list item nên phân cách bằng border nhạt hoặc một khoảng trắng lớn (`gap-6`).
+- Avatar, Tiêu đề, và Thời gian (Metadata) là 3 thứ bắt buộc phải có hệ thống phân cấp rõ ràng (Avatar lớn nhất, Tiêu đề đậm, Thời gian mờ).
+
+## 3. Data Visualization (Biểu đồ)
+- Không dùng quá 4 màu trong 1 biểu đồ tròn (Pie chart).
+- Line chart nên có gradient fill phía dưới đường kẻ để tạo chiều sâu.
+- Các trục (Axes) nên dùng màu mờ (`text-slate-400`) để không cạnh tranh với dữ liệu.

package/.agents/knowledge/design-intelligence/patterns/empty-states.md

@@ -0,0 +1,18 @@
+# Empty States (Trạng thái rỗng)
+
+Màn hình trống không được phép chỉ hiển thị "Chưa có dữ liệu". Phải luôn dẫn dắt người dùng.
+
+## 1. Cấu trúc chuẩn
+- **Hình ảnh/Icon**: Một hình minh họa tinh tế hoặc Icon lớn màu xám nhạt (`text-slate-300`).
+- **Tiêu đề chính**: Giải thích rõ tại sao không có dữ liệu (Vd: "Bạn chưa có dự án nào").
+- **Mô tả phụ**: Hướng dẫn người dùng phải làm gì tiếp theo.
+- **Primary CTA (Nút)**: Nút hành động nổi bật (Vd: "Tạo dự án mới").
+
+## 2. Các trường hợp sử dụng
+- **Lần đầu sử dụng (Onboarding)**: Giới thiệu tính năng.
+- **Xóa sạch dữ liệu (Cleared)**: Khi user đã hoàn thành công việc (Vd: Inbox Zero). Khen ngợi user!
+- **Lỗi tìm kiếm (No Results)**: Cung cấp tùy chọn xóa bộ lọc (Clear Filters).
+
+## 3. Visual Styling
+- Nằm ở trung tâm khu vực hiển thị (Center-aligned).
+- Giới hạn chiều rộng (`max-w-sm`) để text không bị dàn mỏng.

package/.agents/knowledge/design-intelligence/patterns/forms.md

@@ -0,0 +1,15 @@
+# Form Design Patterns
+
+## 1. Bố cục Form (Layout)
+- **1 cột (Single Column)**: Mọi Input nên xếp thành 1 cột từ trên xuống. Đây là cách dễ điền nhất. Chỉ để 2 input trên cùng 1 hàng nếu chúng có quan hệ mật thiết (Vd: Họ và Tên).
+- **Top-aligned Labels**: Nhãn (Label) luôn nằm trên Input, không nằm ngang hàng. Giúp việc quét mắt nhanh hơn.
+- Phân tách Form dài: Chia thành nhiều phần (Sections) hoặc dùng Stepper.
+
+## 2. Feedback & Validation
+- **Inline Validation**: Báo lỗi ngay sau khi user nhập xong (onBlur), không chờ đến lúc bấm Submit.
+- **Error Messages**: Phải có màu đỏ, kèm theo Icon cảnh báo, giải thích rõ cách sửa lỗi.
+- Trạng thái thành công: Có dấu check màu xanh (`text-emerald-500`) bên trong input.
+
+## 3. Nút Submit
+- Không bao giờ đặt chữ "Submit". Hãy dùng Động từ cụ thể: "Tạo tài khoản", "Lưu thay đổi", "Gửi tin nhắn".
+- Khi đang xử lý, nút phải bị disable và có spinner.

package/.agents/knowledge/design-intelligence/references/accessibility.md

@@ -0,0 +1,13 @@
+# Accessibility (A11y) Intelligence
+
+## 1. Focus Management
+- KHÔNG BAO GIỜ loại bỏ `outline: none` mà không có trạng thái thay thế (như `box-shadow`).
+- Tailwind: Luôn dùng `focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-500` để Focus Ring chỉ hiện khi dùng phím Tab (bàn phím), không hiện khi dùng chuột click.
+
+## 2. Screen Readers
+- Những icon chỉ có tính trang trí (decorative) phải có `aria-hidden="true"`.
+- Nút bấm chỉ chứa Icon phải có `aria-label="Tên hành động"` (Vd: aria-label="Đóng").
+
+## 3. Tương phản (Contrast)
+- Sử dụng công cụ đo tương phản để đảm bảo Text/Background đạt chuẩn WCAG AA (Tương phản >= 4.5:1).
+- Chữ xám trên nền xám nhạt là kẻ thù của người cận thị. Luôn dùng ít nhất `text-slate-600` trên nền trắng.

package/.agents/knowledge/design-intelligence/references/tailwind-preset.md

@@ -0,0 +1,17 @@
+# Tailwind Preset Recommendations
+
+## 1. Tùy chỉnh Cốt lõi (Core Configurations)
+Để đạt chuẩn Pro-max, cấu hình `tailwind.config.js` nên thêm các mở rộng sau:
+
+- **Colors**: Sử dụng `colors.slate` hoặc `colors.zinc` làm nền tảng xám.
+- **Fonts**: 
+  - `sans: ['Inter', 'sans-serif']` (Hiện đại, sạch sẽ)
+  - `serif: ['Merriweather', 'serif']` (Cho typography)
+  - `mono: ['JetBrains Mono', 'monospace']` (Cho code)
+
+## 2. Custom Utilities
+- Định nghĩa các bóng đổ riêng mượt hơn mặc định của Tailwind (Radix UI shadow patterns).
+- Định nghĩa keyframes cho micro-animations (slideUpAndFade, scaleIn).
+
+## 3. Design System Plugin
+Khuyến khích tích hợp CVA (Class Variance Authority) hoặc Tailwind Merge để quản lý state của Component dễ dàng hơn trong React/Vue.

package/.agents/knowledge/design-intelligence/templates/auth.md

@@ -0,0 +1,13 @@
+# Authentication Template Intelligence
+
+## 1. Split Screen Layout
+- Chế độ chia đôi màn hình: Trái (hoặc phải) là form Đăng nhập/Đăng ký. Nửa còn lại là Hình ảnh minh họa chất lượng cao hoặc Quote (Trích dẫn) từ khách hàng.
+- Nửa chứa hình ảnh thường ẩn đi trên Mobile (`hidden lg:block`).
+
+## 2. Card Centered Layout
+- Form đăng nhập được đặt trong một Card nằm chính giữa màn hình. Background của trang thường là màu xám nhạt hoặc có subtle pattern.
+
+## 3. Form Focus
+- Bỏ đi NavBar/Footer thừa thãi để user tập trung 100% vào việc đăng nhập.
+- Luôn có nút "Sign in with Google/Apple" (Social Login) nằm trên cùng hoặc dưới cùng, dùng outline style.
+- Liên kết "Quên mật khẩu?" luôn nằm cùng hàng với nhãn "Mật khẩu".

package/.agents/knowledge/design-intelligence/templates/dashboard.md

@@ -0,0 +1,15 @@
+# Dashboard Template Intelligence
+
+## 1. Cấu trúc Layout phổ biến
+- **Sidebar Navigation**: Menu bên trái, nội dung bên phải. Sidebar thường rộng 240px-280px.
+- **Top Navigation**: Menu nằm ngang phía trên. Phù hợp cho app ít tính năng.
+- **Hybrid**: Sidebar cho các module chính, Topbar cho Search, Notifications, và Profile.
+
+## 2. Kích thước & Lưới
+- Dùng CSS Grid cho các thẻ thống kê (Stats Cards): `grid-cols-1 md:grid-cols-2 lg:grid-cols-4`.
+- Khu vực hiển thị (Main Content): Cần có padding cố định (Vd: `p-6` hoặc `p-8`), nền xám rất nhạt (`bg-slate-50`) để tách biệt với nền trắng của các Card.
+
+## 3. Phân cấp thông tin
+- Dòng trên cùng: Các con số KPI quan trọng nhất (Doanh thu, Người dùng).
+- Dòng thứ 2: Biểu đồ xu hướng (Charts).
+- Phía dưới: Bảng dữ liệu chi tiết (Data Table) hoặc Hoạt động gần đây (Recent Activity).

package/.agents/knowledge/design-intelligence/templates/landing-page.md

@@ -0,0 +1,18 @@
+# Landing Page Template Intelligence
+
+## 1. Hero Section (Mặt tiền)
+Quan trọng nhất, quyết định 80% tỉ lệ chuyển đổi.
+- **Tiêu đề chính (H1)**: Chữ cực lớn (text-5xl đến 7xl), font đậm (bold/extrabold), tracking-tight.
+- **Đoạn mô tả (Subtitle)**: Màu xám trung tính (`text-slate-500`), max-width 2xl.
+- **CTA Group**: 1 nút Primary lớn, 1 nút Secondary (hoặc Video Link).
+- **Social Proof**: "Được tin dùng bởi..." + Logo các đối tác màu xám mờ.
+
+## 2. Features Section (Tính năng)
+- Layout Z-Pattern: Chữ bên trái, Ảnh bên phải -> Hàng tiếp theo đổi lại (Ảnh trái, Chữ phải).
+- Hoặc Layout Grid: 3-4 Card chứa Icon, Tiêu đề nhỏ, Mô tả.
+
+## 3. Pricing Section (Bảng giá)
+- Phải có ít nhất 3 cột. Cột ở giữa (Gói phổ biến) cần được làm nổi bật (Viền màu, Scale lớn hơn một chút, có thẻ "Most Popular").
+
+## 4. Footer
+- Background tối màu (`bg-slate-900`), chữ sáng màu. Chia lưới 4-5 cột cho các link điều hướng.

package/.agents/knowledge/design-intelligence/themes/minimal.md

@@ -0,0 +1,15 @@
+# Minimal / Apple-like Theme Intelligence
+
+## 1. Đặc trưng thị giác (Aesthetics)
+- **Less is More**: Tập trung hoàn toàn vào nội dung, loại bỏ mọi đường kẻ ngang/dọc (borders) nếu không thực sự cần thiết. Phân cách bằng khoảng trắng (Whitespace).
+- **Monochrome Focus**: Chủ yếu dùng Đen, Trắng, và các dải Xám. Chỉ dùng màu nhấn ở đúng vị trí tương tác (Link, Active state).
+- **Rounded Corners**: Bo góc mềm mại nhưng không quá lố (thường `rounded-2xl` cho thẻ lớn, `rounded-lg` cho nút). Tương đương Apple iOS / macOS.
+
+## 2. Spacing
+- Cực kỳ phóng khoáng. Padding và Margin rất lớn để tạo cảm giác "thở" cho giao diện.
+- Không lèn chặt thông tin. Giữa tiêu đề và nội dung là khoảng trống rõ ràng.
+
+## 3. Typography
+- Kích thước chữ lớn hơn bình thường (Large Typography).
+- Tiêu đề dùng font weight Bold (700) kết hợp `tracking-tight`.
+- Màu text: Đen nhạt (`text-gray-900`) thay vì đen tuyền để dịu mắt, xám vừa (`text-gray-500`) cho subtitle.

package/.agents/knowledge/design-intelligence/themes/saas.md

@@ -0,0 +1,16 @@
+# SaaS / Vercel-like Theme Intelligence
+
+## 1. Đặc trưng thị giác (Aesthetics)
+- **Tech-forward, Slick & Precise**: Đại diện cho sự hiện đại, công nghệ cao (Thường thấy ở Vercel, Linear, Stripe, Raycast).
+- **Borders & Shadows**: Sử dụng viền 1px siêu mỏng (`border-slate-200` hoặc `border-white/10` trong dark mode), kết hợp với shadow có độ mờ nhạt và đổ bóng nhiều lớp (multi-layered shadows).
+- **Micro-interactions**: Hover effects tinh tế, transition mượt (`transition-all duration-200`).
+
+## 2. Dark Mode Focus (Chủ đạo)
+- Thay vì đen hoàn toàn, nền chính thường là `#09090b` (Zinc 950) hoặc `#020617` (Slate 950).
+- Text: Dùng các sắc thái xám khác nhau để phân cấp (Primary text: `text-slate-200`, Secondary text: `text-slate-400`).
+- Glow effects: Dùng box-shadow dạng glow hoặc `radial-gradient` làm nền mờ ảo sau các nút bấm chính hoặc card quan trọng.
+
+## 3. Typography
+- **Inter** hoặc các font Sans-serif trung tính.
+- Tracking (Letter spacing) hơi khít (`tracking-tight`) cho tiêu đề lớn để trông hiện đại hơn.
+- Text `transparent bg-clip-text bg-gradient-to-r` cực kỳ phổ biến cho tiêu đề (H1).

package/.agents/knowledge/design-intelligence/visual-language/animation.md

@@ -0,0 +1,20 @@
+# Animation & Micro-interactions Intelligence
+
+## 1. Principles
+- **Mục đích**: Animation không bao giờ được dùng chỉ để "trang trí". Nó phải giúp người dùng hiểu trạng thái của hệ thống (Vd: Modal mở ra từ đâu, Nút bấm đã được nhấn chưa).
+- **Tốc độ (Duration)**: Nhanh gọn. Thường từ \`150ms\` đến \`300ms\`. Không bao giờ kéo dài quá \`500ms\` (Trừ các Splash screen).
+- **Easing**: Dùng các đường cong easing mượt mà (Tailwind: \`ease-out\` khi vào màn hình, \`ease-in\` khi thoát ra).
+
+## 2. Micro-interactions chuẩn
+- **Hover Nút**: Thay đổi độ sáng/shadow trong \`200ms\`. (Tailwind: \`transition-all duration-200 ease-in-out\`).
+- **Click Nút (Active)**: Phản hồi nhún xuống 1 chút (Scale). (Tailwind: \`active:scale-95\`).
+- **Card Hover**: Trượt nhẹ lên trên (\`-translate-y-1\`) và tăng đổ bóng (\`shadow-md\`).
+
+## 3. Chuyển cảnh (Transitions & Modals)
+- **Modal/Dialog**: Nên trượt nhẹ từ dưới lên (Slide Up) hoặc phóng to nhẹ từ giữa (Scale In) kết hợp mờ dần (Fade In).
+- **Dropdown/Popover**: Mở nhanh (\`150ms ease-out\`) từ điểm trigger.
+- **Accordion/Collapse**: Không bị giật chiều cao. Nội dung mở ra cần mượt mà.
+
+## 4. Performance
+- Chỉ animate \`transform\` và \`opacity\`.
+- TUYỆT ĐỐI KHÔNG animate các thuộc tính layout như \`width\`, \`height\`, \`top\`, \`left\`, \`margin\`, \`padding\` (Gây Reflow, làm giật lag trình duyệt).

package/.agents/knowledge/design-intelligence/visual-language/color.md

@@ -0,0 +1,24 @@
+# Color Intelligence (Hệ thống màu sắc & Tương phản)
+
+## 1. Quy tắc 60-30-10
+Áp dụng cho mọi giao diện để tạo cân bằng thị giác:
+- **60% (Màu nền - Background)**: Thường là trắng, xám nhạt (Light mode) hoặc đen, xám đậm (Dark mode). Tailwind: `bg-white` / `bg-slate-900`.
+- **30% (Màu phụ - Secondary/Surface)**: Các thành phần phân cách như Card background, Sidebar, Border. Tailwind: `bg-slate-50` / `border-slate-200`.
+- **10% (Màu nhấn - Primary/Accent)**: CTA Buttons, link, icon đang active. Tạo sự thu hút chú ý ngay lập tức.
+
+## 2. Semantic Colors (Màu ngữ nghĩa)
+Không bao giờ dùng màu đỏ cho nút OK, không dùng xanh lá cho Cảnh báo.
+- **Primary**: Brand color (Vd: Blue-600).
+- **Success**: Green (Tailwind: `emerald-500`).
+- **Warning**: Yellow/Orange (Tailwind: `amber-500`).
+- **Danger/Destructive**: Red (Tailwind: `rose-500` hoặc `red-500`).
+- **Info**: Blue (Tailwind: `blue-500`).
+
+## 3. Quản lý Dark Mode (SaaS Trend)
+Thay vì dùng màu đen tuyền `#000000`, hãy dùng các tone xám ám màu nhẹ (Tinted Grays) để bớt chói mắt:
+- **Slate** (Ám xanh dương) - Phù hợp Tech/SaaS.
+- **Zinc** (Xám trung tính) - Phù hợp Minimal/Editorial.
+- Text trong Dark Mode không bao giờ dùng trắng tinh (`#ffffff`), nên dùng xám rất nhạt (Tailwind: `text-slate-200`).
+
+## 4. Accessibility (Độ tương phản A11y)
+Luôn đảm bảo độ tương phản giữa Text và Background đạt tối thiểu **4.5:1** (WCAG AA). Text nhỏ cần tương phản cao hơn text lớn.

package/.agents/knowledge/design-intelligence/visual-language/layout.md

@@ -0,0 +1,18 @@
+# Layout Intelligence (Bố cục)
+
+## 1. Container & Max-Width
+Không bao giờ để văn bản chạy tràn màn hình siêu rộng (Ultra-wide).
+- Đọc tối ưu: Đoạn văn chỉ nên dài từ 60-80 ký tự/dòng. (Tailwind: `max-w-prose` hoặc `max-w-2xl`).
+- Main Layout: Thường bọc trong một container có max-width (Tailwind: `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8`).
+
+## 2. Flex vs Grid
+- **Flexbox**: Dành cho giao diện 1 chiều (hàng hoặc cột). Ví dụ: Navbar, Danh sách tag, Nhóm nút bấm.
+- **CSS Grid**: Dành cho bố cục 2 chiều, các Card đều nhau. (Tailwind: `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6`).
+
+## 3. Responsive Breakpoints
+Tư duy Mobile-First:
+- Code mặc định luôn áp dụng cho Mobile (Màn hình dọc).
+- `sm:` (640px) - Tablet nhỏ.
+- `md:` (768px) - Tablet ngang / iPad.
+- `lg:` (1024px) - Desktop / Laptop.
+- Tránh dùng quá nhiều breakpoint trên 1 class, chỉ dùng khi layout thực sự vỡ.

package/.agents/knowledge/design-intelligence/visual-language/spacing.md

@@ -0,0 +1,19 @@
+# Spacing Intelligence (Khoảng cách & Lưới)
+
+## 1. Hệ thống Lưới 8pt (8-Point Grid System)
+Khoảng cách (Margin/Padding), kích thước Icon, chiều cao Component **PHẢI** là bội số của 8 (hoặc 4 đối với chi tiết nhỏ).
+- 4px (`gap-1`, `p-1`)
+- 8px (`gap-2`, `p-2`)
+- 12px (`gap-3`, `p-3`) - Phổ biến cho padding bên trong nút bấm.
+- 16px (`gap-4`, `p-4`) - Base padding cho Card, Container nhỏ.
+- 24px (`gap-6`, `p-6`) - Khoảng cách giữa các sections nhỏ.
+- 32px (`gap-8`, `p-8`) - Padding tiêu chuẩn cho Container lớn.
+- 48px (`gap-12`, `p-12`) / 64px (`gap-16`) - Khoảng cách giữa các Section chính của Landing Page.
+
+## 2. Quy luật gần gũi (Law of Proximity)
+Các thành phần có liên quan logic với nhau phải nằm gần nhau hơn so với các phần khác.
+- Ví dụ Card: Khoảng cách giữa Icon và Text (8px) phải nhỏ hơn khoảng cách từ Text đến Border (16px).
+- Label và Input: `gap-1` (4px). Giữa 2 Field Form: `gap-4` (16px). Giữa Form và Submit Button: `gap-6` (24px).
+
+## 3. Optical Alignment (Căn chỉnh quang học)
+Đôi khi một icon tròn trông sẽ nhỏ hơn một icon vuông có cùng kích thước (bounding box). Tránh dùng số lẻ, sử dụng lưới 8pt để tự động căn bằng.

package/.agents/knowledge/design-intelligence/visual-language/typography.md

@@ -0,0 +1,23 @@
+# Typography Intelligence (Font Scale & Pairing)
+
+## 1. Hệ thống tỉ lệ (Scale System)
+Dựa trên nguyên lý phổ biến của thị trường (như Tailwind, Radix UI):
+- **Base (16px / 1rem)**: Nội dung đoạn văn mặc định. (Tailwind: `text-base`)
+- **Small (14px / 0.875rem)**: Chú thích, phụ đề nhỏ, label form. (Tailwind: `text-sm`)
+- **Tiny (12px / 0.75rem)**: Badge, tag, footnote. (Tailwind: `text-xs`)
+- **H3 / Subheading (20px / 1.25rem)**: Tiêu đề phụ, card title. (Tailwind: `text-xl`)
+- **H2 / Section Title (24px / 1.5rem)**: Tiêu đề mục lớn. (Tailwind: `text-2xl`)
+- **H1 / Hero Title (36px+ / 2.25rem+)**: Tiêu đề trang, landing page hero. (Tailwind: `text-4xl` hoặc `text-5xl`)
+
+## 2. Line Height (Chiều cao dòng)
+- Tiêu đề (H1, H2): Dùng `1.1` đến `1.2` (Tailwind: `leading-tight`) để tránh khoảng trống thừa.
+- Đoạn văn (Paragraph): Dùng `1.5` đến `1.6` (Tailwind: `leading-relaxed`) để dễ đọc.
+
+## 3. Font Pairing (Ghép cặp font chuẩn)
+- **Modern SaaS**: Inter (Sans-serif) cho toàn bộ, hoặc Cal Sans cho tiêu đề + Inter cho nội dung.
+- **Editorial / Blog**: Merriweather (Serif) cho tiêu đề + Roboto (Sans-serif) cho nội dung.
+- **Developer / Tech**: Fira Code hoặc JetBrains Mono cho code/badge + System UI (San Francisco/Segoe UI) cho UI.
+
+## 4. Trọng lượng chữ (Font Weight)
+- Tránh dùng Semibold (600) tràn lan. Dùng Medium (500) cho button/label và Bold (700) cho tiêu đề.
+- Body text luôn là Regular (400).

package/.agents/skills/qk-ui-system-builder/SKILL.md

@@ -48,6 +48,19 @@ knowledge_scope:
   references:
     - design-system
 
+decision_boundary:
+  owns:
+    - tokens
+    - ui-system
+  does_not_own:
+    - page implementation
+    - visual direction
+  conflicts_with:
+    - qk-design-system-engineering
+
+knowledge_dependencies:
+  - design-intelligence
+
 # ── V8: Verification ───────────────────────────────────────
 verification:
   required: true

package/CHANGELOG.md

@@ -5,6 +5,28 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ---
 
+## [8.1.7] — 2026-07 — README Sync
+
+### Changed
+- **README Sync**: Synced `.agents/README.md` with root `README.md` so the installed documentation is fully up-to-date with V8.1 architecture.
+- Bumped version to `8.1.7`.
+
+---
+
+## [8.1.6] — 2026-07 — Design Intelligence Content & Sync
+
+### Added
+- **Design Intelligence Populated**: Sourced core market-standard knowledge (Tailwind, Radix, Apple, Vercel-like principles) into `.agents/knowledge/design-intelligence/` covering components, patterns, industries, themes, and references.
+- **Animation Knowledge**: Added `visual-language/animation.md` for micro-interactions and transition durations.
+- **Dependency Wiring**: Linked `qk-ui-system-builder` to `design-intelligence` so it utilizes the newly generated design constraints.
+- **Changelog Sync**: Synced `.agents/CHANGELOG.md` with root `CHANGELOG.md` so the installed copy reflects the true V8 evolution.
+
+### Changed
+- All skill descriptions properly translated to Vietnamese for ecosystem consistency.
+- Bumped version to `8.1.6` for final, truly complete Design Intelligence NPM Release.
+
+---
+
 ## [8.1.4] — 2026-07 — Design Intelligence Pack
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-developer-skill-os",
-  "version": "8.1.4",
-  "description": "Agent Engineering OS Framework with Design Intelligence, AI coding agents (Claude, Cursor, Windsurf, Antigravity) with 30 Master Skills.",
+  "version": "8.1.7",
+  "description": "Agent Engineering OS: A deterministic capability graph, governance rules, and dynamic knowledge base for AI coding agents.",
   "main": "bin/install.js",
   "files": [
     "bin",