# 🤖 AGENTS.md — Hướng Dẫn Vận Hành AI Agents Cho Dự Án Handy

> File này là điểm tiếp cận nhanh dành cho tất cả các trợ lý AI (Google Antigravity, Cursor, Claude Code, GitHub Copilot, OpenClaw) khi làm việc trong repository này.

---

## 🎯 BỐI CẢNH & PHÂN ĐỊNH TRỌNG TÂM CỐT LÕI

1. **SẢN PHẨM CHÍNH (Core Product): Handy**
   - **Vị trí**: `macos-handy/`
   - **Bản chất**: Ứng dụng native macOS (Swift 6.0, AppKit, SwiftUI) điều khiển chuột và hệ thống bằng cử chỉ bàn tay không gian 3D qua camera FaceTime / iPhone Continuity Camera.
   - **Điểm mạnh**: Chạy trên Apple Neural Engine (ANE), độ trễ < 8ms, 60 FPS, vòng đời Zero-CPU tiết kiệm pin.

2. **BẢN DEMO THỰC NGHIỆM (Showcase Demo): Fulldy Warehouse 3D**
   - **Vị trí**: `demos/warehouse/`
   - **Bản chất**: Ứng dụng mô phỏng kho hàng 3D Digital Twin (Three.js WebGL, bitECS 0.4 SoA) đóng vai trò là bản demo tương tác (Killer Showcase) chứng minh khả năng điều khiển không gian của Handy.

---

## 📁 BẢN ĐỒ CẤU TRÚC WORKSPACE

```
/
├── index.html                 # Landing Page chính thức của Handy (tích hợp link Demo)
├── package.json               # Cấu hình workspace & scripts Handy / Demo
├── README.md                  # Tài liệu tổng quan dự án
├── AGENTS.md                  # File hướng dẫn nhanh này
├── MASTER_PROMPT.md           # Master prompt copy-paste khởi động trên máy mới
├── .agents/                   # KHO TRI THỨC CHUYÊN SÂU DÀNH CHO AI AGENTS:
│   ├── README.md              # Mục lục điều hướng
│   ├── PROJECT_CONTEXT.md     # Tầm nhìn, bài toán & ý tưởng giải pháp
│   ├── ARCHITECTURE.md        # Kiến trúc kỹ thuật & ranh giới phân tầng
│   ├── ROLES.md               # Ma trận 6 vai trò sub-agents chuyên biệt
│   └── RULES.md               # 5 nguyên tắc Hard Gates (An ninh, Cách ly, TDD)
├── macos-handy/               # SẢN PHẨM CHÍNH: ỨNG DỤNG MACOS NATIVE
│   ├── Package.swift          # SPM Package Definition
│   ├── Sources/Handy/         # Mã nguồn Swift (Engine, Vision, UI, App)
│   ├── Resources/             # AppIcon.icns, MenuBar icons
│   ├── Scripts/build-handy.sh # Script đóng gói Handy.app & zip release
│   └── build/                 # Thư mục chứa Handy.app hoàn chỉnh
├── demos/warehouse/           # BẢN DEMO THỰC NGHIỆM: KHO HÀNG 3D DIGITAL TWIN
│   ├── index.html             # 3D Warehouse Simulator
│   ├── warehouse-3d-models.html # 3D Low-Poly Mesh Studio
│   ├── game-design-system.html  # Game Design System
│   ├── boxme-mission-control.html # Mission Control Telemetry
│   ├── src/                   # bitECS, FlowField, Procedural Mesh, Tests
│   ├── bin/fulldy-cli.js      # Terminal Dashboard & Monitor
│   ├── functions/             # Cloudflare Pages Auth Functions
│   └── assets -> ../../assets # Symlink chia sẻ assets đồ họa
└── assets/                    # TÀI NGUYÊN ĐỒ HỌA DÙNG CHUNG
    ├── branding/              # Bộ nhận diện Handy (Icon, Favicon, Banner)
    ├── images/                # Ảnh isometric, props, thiết bị kho
    └── vendor/                # Thư viện Three.js, OrbitControls
```

---

## ⚡ CÁC LỆNH VẬN HÀNH THƯỜNG DÙNG (CLI CHEAT SHEET)

```bash
# ==============================================================================
# 🍎 HANDY MACOS NATIVE APP (SẢN PHẨM CHÍNH)
# ==============================================================================
# Biên dịch mã nguồn Swift 6.0 và đóng gói Handy.app release:
npm run handy:build
# hoặc:
npm run build

# Khởi chạy ứng dụng Handy trực tiếp trên macOS:
npm run handy:run
# hoặc:
npm run run

# Tái tạo bộ nhận diện thương hiệu chuẩn Apple HIG (AppIcon.icns, MenuBar):
npm run branding:build

# ==============================================================================
# 🎮 FULLDY WAREHOUSE 3D DEMO (BẢN DEMO THỰC NGHIỆM)
# ==============================================================================
# Mở Terminal Dashboard quản trị kho hàng:
npm run demo:warehouse

# Chạy chế độ giám sát tự động thời gian thực (Live Monitor mỗi 2s):
npm run demo:monitor

# Chạy toàn bộ 39 Unit Tests của bản mô phỏng:
npm run demo:test
# hoặc:
npm test

# ==============================================================================
# 🛡️ AN NINH & CHẤT LƯỢNG
# ==============================================================================
# Quét toàn diện repository chặn RCE, script shell độc và copyleft AGPL:
npm run audit
```

---

## 🔒 3 NGUYÊN TẮC BẮT BUỘC KHI VIẾT CODE CHO DỰ ÁN

1. **Không Trộn Lẫn Code**: Tuyệt đối không import mã Three.js hay bitECS vào thư mục `macos-handy/`. Hai hệ thống chỉ giao tiếp qua IPC bridge.
2. **Ngân Sách Tiết Kiệm Pin**: Đảm bảo Handy duy trì 60 FPS khi ACTIVE, 3 FPS khi IDLE, và 0.0% CPU khi DEEP SLEEP.
3. **Bằng Chứng Trước Khi Hoàn Thành**: Luôn chạy `npm run handy:build`, `npm test` và `npm run audit` trước khi báo cáo kết quả cho người dùng.

> 📖 Để tìm hiểu sâu hơn, hãy đọc toàn bộ tài liệu trong thư mục [`.agents/`](file:///.agents/).