@mrtrinhvn/ag-kit 1.1.4 → 1.1.6

package/README.md

@@ -4,8 +4,14 @@ A generic, institutional-grade AI programming framework for automating scaffoldi
 
 ## 📦 Quick Start
 
-The best way to inject AG-Kit into any project is via `npx`:
+The best way to inject AG-Kit into any project is via `npx`. Bạn có thể chạy trực tiếp để vào **Menu tương tác**:
 
+```bash
+# DASHBOARD - Menu chọn tất cả tác vụ (Khuyên dùng)
+npx @mrtrinhvn/ag-kit@latest
+```
+
+Hoặc chạy các lệnh đơn lẻ:
 ```bash
 # 1. Khởi tạo bộ não (Inject .agent folder)
 npx @mrtrinhvn/ag-kit@latest init
@@ -23,6 +29,7 @@ npx @mrtrinhvn/ag-kit@latest status
 
 | Lệnh | Ý nghĩa | Chi tiết |
 |---|---|---|
+| `ag-kit` | **Dashboard** | (Không tham số) Mở menu chọn tương tác cực kỳ tiện lợi. |
 | `ag-kit init` | **Khởi tạo** | Cài đặt tủy não `.agent` và tạo file `.env` mẫu. |
 | `ag-kit check` | **Kiểm tra** | Quét cổng CDP (mặc định 9555), kiểm tra Ollama và AI Models. |
 | `ag-kit update` | **Cập nhật** | Nâng cấp Agents/Skills/Workflows mới nhất mà không làm mất dữ liệu Ký ức. |
@@ -66,7 +73,8 @@ npx @mrtrinhvn/ag-kit@latest update
 
 **1. Lỗi phiên bản không khớp (Version ghosting):**
 Nếu `status` báo phiên bản cũ hơn bản trên NPM, đó là do cache của `npx` hoặc bạn đã cài global. 
-- Cách giải quyết: Luôn thêm `@latest` sau tên gói hoặc chạy `sudo npm install -g @mrtrinhvn/ag-kit@latest`.
+- Cách giải quyết: Luôn thêm `@latest` sau tên gói (`npx @mrtrinhvn/ag-kit@latest`) hoặc cập nhật bộ não bằng lệnh `ag-kit update`.
+- Giờ đây, các lệnh `init` và `status` sẽ tự động phát hiện và nhắc bạn chạy `update` nếu phát hiện lệch phiên bản.
 
 **2. Lỗi EACCES (Quyền truy cập):**
 Nếu cài global bị báo lỗi quyền, hãy dùng `npx` (Khuyên dùng) hoặc dùng `sudo`.

package/bin/cli.js

@@ -90,7 +90,18 @@ program.command('init')
         }
       }
     } else {
-      console.log('\x1b[33m⚠️ Thư mục .agent đã tồn tại. Hãy dùng lệnh "update" để cập nhật.\x1b[0m');
+      console.log('\x1b[33m⚠️ Thư mục .agent đã tồn tại.\x1b[0m');
+      const vPath = path.join(TARGET_AGENT_DIR, '.version');
+      if (fs.existsSync(vPath)) {
+        const installedVersion = fs.readFileSync(vPath, 'utf-8').trim();
+        if (installedVersion !== pkg.version) {
+          console.log(`\x1b[35m👉 Phát hiện phiên bản cũ (v${installedVersion}). Hãy dùng lệnh "ag-kit update" để cập nhật lên v${pkg.version}.\x1b[0m`);
+        } else {
+          console.log('\x1b[34mℹ️  Bạn đang sử dụng phiên bản khớp với bộ công cụ (v${pkg.version}).\x1b[0m');
+        }
+      } else {
+        console.log('\x1b[35m👉 Hãy dùng lệnh "ag-kit update" để đồng bộ cấu trúc mới.\x1b[0m');
+      }
     }
 
     console.log('\x1b[35m\n🎉 Hoàn tất! Vui lòng copy luật GEMINI vào file GEMINI.md của dự án nếu chưa có.\x1b[0m');
@@ -127,6 +138,12 @@ program.command('check')
   .action(async () => {
     const { execSync } = require('child_process');
     console.log('\x1b[36m🔍 Đang kiểm tra hệ sinh thái Antigravity...\x1b[0m');
+    
+    if (!fs.existsSync(TARGET_AGENT_DIR)) {
+      console.log('\x1b[31m❌ Hệ thống chưa được khởi tạo. Thư mục .agent không tồn tại.\x1b[0m');
+      console.log('\x1b[35m👉 Hãy chạy "ag-kit init" trước khi thực hiện kiểm tra này.\x1b[0m');
+      return;
+    }
 
     // 1. Check .env
     const envPath = path.join(process.cwd(), '.env');
@@ -203,8 +220,9 @@ program.command('status')
       console.log(`📁 Đường dẫn    : ${TARGET_AGENT_DIR}`);
       
       const vPath = path.join(TARGET_AGENT_DIR, '.version');
+      let installedVersion = '0.0.0';
       if (fs.existsSync(vPath)) {
-        const installedVersion = fs.readFileSync(vPath, 'utf-8').trim();
+        installedVersion = fs.readFileSync(vPath, 'utf-8').trim();
         console.log(`🧠 Bản cài đặt  : v${installedVersion}`);
       } else {
         console.log(`🧠 Bản cài đặt  : Không rõ (Legacy)`);
@@ -212,10 +230,41 @@ program.command('status')
 
       console.log(`🏷  Bản Tool     : v${pkg.version}`);
       
+      if (installedVersion !== pkg.version) {
+        console.log('\n\x1b[33m⚠️  CẢNH BÁO: Phiên bản bộ não (.agent) đang lệch với bộ công cụ (ag-kit)!\x1b[0m');
+        console.log(`\x1b[35m👉 Hãy chạy "ag-kit update" để đồng bộ ngay.\x1b[0m`);
+      }
+      
     } else {
-      console.log('\x1b[31m❌ Trạng thái  : Chưa có gì. Gõ "ag-kit init" để Setup.\x1b[0m');
+      console.log('\x1b[31m❌ Trạng thái  : Chưa có gì.\x1b[0m');
+      console.log('\x1b[35m👉 Gõ "ag-kit init" để biến thư mục này thành một Agentic Workspace!\x1b[0m');
       console.log(`🏷  Bản Tool     : v${pkg.version}`);
     }
   });
 
-program.parse(process.argv);
+
+if (process.argv.length <= 2) {
+  const inquirer = require('inquirer');
+  console.log('\x1b[35m\n🧠 ANTIGRAVITY KIT - BẢNG ĐIỀU KHIỂN TÁC VỤ\x1b[0m');
+  inquirer.prompt([
+    {
+      type: 'list',
+      name: 'action',
+      message: 'Chọn một tác vụ để thực hiện:',
+      choices: [
+        { name: '🚀 Khởi tạo (init) - Cài đặt .agent', value: 'init' },
+        { name: '🔄 Cập nhật (update) - Nâng cấp bộ não', value: 'update' },
+        { name: '🔍 Kiểm tra (check) - Test môi trường', value: 'check' },
+        { name: '📊 Trạng thái (status) - Xem version', value: 'status' },
+        new inquirer.Separator(),
+        { name: '❌ Thoát', value: 'exit' }
+      ]
+    }
+  ]).then(answers => {
+    if (answers.action !== 'exit') {
+      program.parse([process.argv[0], process.argv[1], answers.action]);
+    }
+  });
+} else {
+  program.parse(process.argv);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
   "main": "index.js",
   "bin": {
@@ -29,6 +29,7 @@
     "package.json"
   ],
   "dependencies": {
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "inquirer": "^8.2.5"
   }
 }

package/template/.agent/agents/orchestrator.md

@@ -30,6 +30,8 @@ You are the master orchestrator agent. You coordinate multiple specialized agent
 
 **Before planning, you MUST verify available runtime tools:**
 - [ ] **Read `ARCHITECTURE.md`** to see full list of Scripts & Skills
+- [ ] **Check `tele-agentic-standard.md`** for Remote Golden Loop awareness.
+- [ ] **Verify IDE HUD status**: If `ag_portal_bridge.js` is active, use it for real-time reporting.
 - [ ] **Identify relevant scripts** (e.g., `playwright_runner.py` for web, `security_scan.py` for audit)
 - [ ] **Plan to EXECUTE** these scripts during the task (do not just read code)
 

package/template/.agent/knowledge/model-switching-vfs.md

@@ -1,22 +1,22 @@
-# Tiết Kiệm Token & Quản Lý Mô Hình (Model & VFS Knowledge)
+# Tiết Kiệm Token & Chiến Lược Mô Hình (Model & VFS)
 
-## 1. Cơ Chế Tiết Kiệm Token
-Trong môi trường điều khiển từ xa (Telegram), việc tối ưu hóa token là cực kỳ quan trọng để duy trì hiệu suất và chi phí.
+Tiết kiệm tài nguyên là yếu tố sống còn khi vận hành AI Agentic lâu dài. Hệ thống tuân thủ nghiêm ngặt các nguyên tắc sau:
 
-### VFS (Virtual File System)
-- **Tác dụng**: Giảm 98% lượng token khi khám phá mã nguồn.
-- **Cách hoạt động**: Thay vì đọc toàn bộ file, AI sử dụng công cụ `vfs` để chỉ lấy chữ ký (signatures) của hàm và lớp.
-- **Quy tắc**: Phải luôn sử dụng `vfs` trước khi dùng `grep` hoặc đọc file đầy đủ. (Xem `GEMINI.md`).
+## 1. Giao Thức VFS (Virtual File System)
+Dựa trên sáng kiến [VFS của TrNgTien](https://github.com/TrNgTien/vfs), chúng ta thay đổi cách AI tiếp cận mã nguồn:
+- **Tác dụng**: Giảm lượng token tiêu thụ lên đến **98%** khi khám phá project lớn.
+- **Quyết định**: AI KHÔNG ĐƯỢC đọc toàn bộ file ngay lập tức. Thay vào đó, AI dùng công cụ `vfs` để quét các "chữ ký" (signatures - tên hàm, lớp, kiểu dữ liệu) trước.
+- **Thứ tự thực hiện**: `vfs search` -> `vfs read signature` -> `read file (chỉ vùng code cần thiết)`.
 
-## 2. Chiến Lược Lựa Chọn Mô Hình (Model Strategy)
-Hệ thống sử dụng cơ chế "Phân tầng độ khó" để chọn model:
+## 2. Phân Tầng Lựa Chọn Mô Hình (Model Hierarchy)
+Hệ thống sử dụng model phù hợp với "độ khó" của bệnh:
 
-| Độ khó | Tác vụ | Mô hình khuyến nghị | Lý do |
+| Cấp độ | Tác vụ | Mô hình khuyến nghị | Ưu điểm |
 | :--- | :--- | :--- | :--- |
-| **Thấp** | Giải thích code, Refactor nhỏ, Chat thông thường | **Ollama (Local)** | Không tốn quota, phản hồi nhanh cho tác vụ đơn giản. |
-| **Trung bình** | Fix lỗi, Thêm tính năng mới | **Gemini 3 Flash** | Cân bằng giữa chi phí và độ thông minh. |
-| **Cao** | Thiết kế kiến trúc, Debug lỗi phức tạp | **Claude 3.5 Sonnet / Gemini 1.5 Pro** | Độ chính xác cao nhất cho các vấn đề hóc búa. |
+| **Sơ cấp** | Giải thích code, Chat hỏi đáp, Refactor nhỏ | **Ollama (Local)** | 0 token cost, Bảo mật, Phản hồi tức thì. |
+| **Trung cấp** | Fix lỗi thông thường, Thêm tính năng đơn giản | **Gemini 3 Flash** | Chi phí thấp, Context window cực lớn. |
+| **Nâng cao** | Thiết kế kiến trúc phức tạp, Debug lỗi logic sâu | **Claude 3.5 Sonnet / Gemini 1.5 Pro** | Độ chính xác và khả năng suy luận mạnh nhất. |
 
-## 3. Tích Hợp Local Model (Ollama)
-- Bot kết nối trực tiếp với Ollama API tại `http://localhost:11434`.
-- Người dùng có thể chọn dùng model local qua lệnh `/model` để "đóng băng" quota Google khi không cần thiết.
+## 3. Tích Hợp Local LLM (Ollama)
+- Cho phép Bot kết nối trực tiếp với Ollama (thường ở `http://localhost:11434`).
+- Thường sử dụng các model nhẹ nhưng hiệu quả như `nemotron`, `llama3`, `qwen2.5`.

package/template/.agent/knowledge/tele-agentic-standard.md

@@ -0,0 +1,32 @@
+# TIÊU CHUẨN GIAO TIẾP TẬP TRUNG (TELE-AGENTIC STANDARD)
+
+Dự án này áp dụng mô hình **Cổng Agentic Hợp Nhất (Unified Agentic Gateway)**, nơi IDE, Bot Telegram và Nhóm Telegram kết nối thành một "Bộ não" duy nhất.
+
+## 📡 KIẾN TRÚC "COMBO VÀNG" (GOLDEN COMBO)
+
+Hệ thống được vận hành bởi 3 trụ cột:
+1.  **IDE (Antigravity)**: Đóng vai trò là **Node Tham gia (Participant)**. Không chỉ để gõ code mà còn là Dashboard trực quan.
+2.  **Telegram Bot/Groups**: Đóng vai trò là **Cổng Giao tiếp & Phê duyệt (Gateway)**.
+3.  **CDP Bridge (`ag_portal_bridge.js`)**: Đóng vai trò là **Hệ thần kinh (Nervous System)** kết nối 2 thành phần trên.
+
+### 1. Phân Lập Trí Nhớ Theo Topic (Group Topics)
+Nhóm Telegram được chia thành các Topic để cô lập bối cảnh:
+-   **Topic 🔴 Surgery (Phẫu thuật)**: Chuyên dụng cho các lệnh `/heal` và workflow `@brain-surgeon`.
+-   **Topic 🟢 Signals (Tín hiệu)**: Hiển thị lệnh mua/bán từ AI.
+-   **Topic 🔵 General (Tổng quan)**: Quản trị hệ thống, lệnh `/status`.
+
+### 2. Giao Diện IDE Portal (HUD)
+IDE nạp file `scripts/ag_hud.js` qua CDP để hiển thị:
+-   **Gen/WinRate**: Chỉ số tiến hóa của AI Brain.
+-   **Stall Alert**: Cảnh báo đỏ khi AI ngừng tiến bộ.
+-   **Doctor Call**: Nút bấm kích hoạt Logic tự chữa lành.
+
+## 🛠️ QUY TRÌNH VẬN HÀNH (OPERATIONAL LOOP)
+
+1.  **Phát hiện (Detect)**: `LearningService` phát hiện lỗi/stall -> Cập nhật `ai_state.json`.
+2.  **Cảnh báo (Alert)**: Bridge đẩy dữ liệu lên HUD IDE (Cảnh báo đỏ) và Bot gửi tin nhắn Telegram Group.
+3.  **Phê duyệt (Approve)**: Người dùng nhấn nút trên HUD hoặc Telegram Callback.
+4.  **Hành động (Act)**: IDE Agent (Antigravity) tự động kích hoạt workflow `/debug` để sửa code.
+
+---
+*Tham chiếu: .agent/skills/telegram-agentic-gateway*

package/template/.agent/skills/knowledge-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-management
-description: Systems thinking and knowledge retention protocol. MANDATORY for maintaining architectural consistency, recording integration knowledge (API characteristics), and ensuring complete, holistic code updates.
+description: Hệ thống tư duy và giao thức duy trì tri thức (Systems Thinking & Knowledge Retention). MANDATORY cho việc duy trì tính nhất quán của kiến trúc, ghi chép tri thức tích hợp (API characteristics) và đảm bảo cập nhật mã nguồn hoàn chỉnh, đồng bộ. **QUY TẮC TỐI THƯỢNG: Khi cập nhật ag-kit, phải đồng bộ sang thư mục `template/`.**
 allowed-tools: Read, Write, Glob, Grep
 ---
 

package/template/.agent/skills/lazy-gravity/SKILL.md

@@ -1,23 +1,20 @@
 ---
 name: lazy-gravity
-description: Cross-platform remote operation patterns for Antigravity, based on the LazyGravity project.
+description: Quản lý đa dự án và phiên làm việc AI từ xa an toàn.
 ---
 
 # Vận Hành Đa Nền Tảng (LazyGravity Patterns)
 
-LazyGravity tập trung vào việc quản lý nhiều dự án và phiên làm việc từ xa một cách an toàn và linh hoạt.
+Kỹ thuật quản lý và luân chuyển bối cảnh được kế thừa từ dự án [LazyGravity](https://github.com/tokyoweb3/LazyGravity).
 
-## Các Đặc Điểm Chính
+## 1. Project & Workspace Discovery
+- **Workspace Scanning**: Tự động duyệt qua `WORKSPACE_DIR` để liệt kê các thư mục dự án con.
+- **Remote Switching**: Lệnh `/project` cho phép User chọn dự án mới. Bot sẽ cập nhật cấu hình và cảnh báo User khởi động lại flow tương ứng.
 
-1. **Project Discovery**: Tự động quét các thư mục trong Workspace để cho phép người dùng chuyển đổi dự án từ xa qua lệnh `/project`.
-2. **Session Management**: Quản lý lịch sử hội thoại (Past Conversations), cho phép chọn lại phiên cũ để tiếp tục làm việc.
-3. **Auto-Accept Flow**: Tích hợp cơ chế tự động nhấn "Accept" cho các file edit nếu người dùng bật chế độ `/autoaccept`.
+## 2. Bảo Mật & Phân Quyền
+- **White-listing**: Chỉ cho phép `ALLOWED_USER_IDS` và `ALLOWED_CHAT_IDS` thực hiện các lệnh nhạy cảm như `/heal` hoặc `/kill`.
+- **Auto-Accept Safety**: Tích hợp chế độ `/autoaccept` cho phép tự động nhấn nút "Accept" trong IDE, nhưng yêu cầu giám sát liên tục qua `/screenshot`.
 
-## Quản Lý Dự Án (Remote Switching)
-
-- Sử dụng `WorkspaceService` để liệt kê các thư mục con.
-- Khi người dùng chọn dự án, bot sẽ cung cấp thông tin hoặc tự động restart target sang dự án mới (nếu được cấp quyền).
-
-## Phân Loại Mô Hình (Model Categorization)
-- Phân tách rõ ràng giữa **Cloud Models** (Google Gemini, Claude) và **Local Models** (Ollama).
-- Ưu tiên Local Models cho các yêu cầu giải thích hoặc refactor nhỏ để tiết kiệm quota Cloud.
+## 3. Đồng Bộ Hóa Trạng Thái
+- Đảm bảo trạng thái của IDE (Generating, Idle, Error) luôn được phản ánh kịp thời lên Telegram Group qua Notifications.
+- Sử dụng cơ chế ID ngắn (Short ID Mapping) để quản lý danh sách Session/File một cách gọn gàng trên giao diện điện thoại.

package/template/.agent/skills/remoat-integration/SKILL.md

@@ -1,24 +1,21 @@
 ---
 name: remoat-integration
-description: Patterns for controlling AI code editors from Telegram, based on the Remoat project.
+description: Kỹ thuật điều khiển AI Editor từ xa qua CDP (Chrome DevTools Protocol).
 ---
 
-# Kỹ Thuật Điều Khiển Editor Từ Xa (Remoat Integration)
+# Kỹ Thuật Điều Khiển Editor Từ Xa (Remoat Strategy)
 
-Kỹ thuật này cho phép điều khiển Antigravity hoặc bất kỳ Editor nào hỗ trợ CDP (Chrome DevTools Protocol) thông qua Telegram.
+Dựa trên nguyên lý của dự án [Remoat](https://github.com/optimistengineer/remoat), cho phép biến Antigravity thành một AI hoàn toàn có thể điều khiển từ xa.
 
-## Nguyên Tắc Cốt Lõi (Remoat Strategy)
+## 1. Giao Thức Kết Nối (CDP Bridge)
+- **Cổng Debug**: Khởi động Editor với tham số `--remote-debugging-port=9555`.
+- **WebSocket Discovery**: Quét danh sách `/json/list` trên localhost để tìm URL WebSocket của `workbench.html`.
 
-1. **Bridge qua CDP**: Không can thiệp vào mã nguồn của Editor. Sử dụng CDP để Inject Prompt và Monitor Response.
-2. **Single Brain Architecture**: Bot Telegram chỉ đóng vai trò "lễ tân", nhận lệnh và chuyển tiếp cho Editor. Editor là "bộ não" thực hiện công việc.
-3. **Wait for Generate**: Sử dụng DOM Observation để biết khi nào AI trong Editor đang suy nghĩ hoặc đã hoàn thành.
+## 2. Các Thao Tác Chuyên Sâu
+- **Inject Prompt**: Tự động tìm `Chat Input`, focus và chèn text, giả lập phím Enter.
+- **Response Monitor**: Quan sát DOM chat để nhận diện khi nào AI bắt đầu/kết thúc trả lời.
+- **Visual Feedback**: Sử dụng `Page.captureScreenshot` để chụp lại giao diện IDE, giúp User quan sát code và lỗi trực quan qua Telegram.
+- **Terminal Control**: Điều khiển terminal của Editor để chạy test hoặc deploy qua lệnh `/cmd`.
 
-## Các Tập Lệnh Đặc Trưng
-
-- `/screenshot`: Chụp ảnh màn hình Editor để kiểm tra kết quả trực quan.
-- `/stop`: Dừng khẩn cấp quá trình sinh code của AI.
-- `/mode`: Chuyển đổi giữa chế độ `fast` (flash models) và `plan` (pro models).
-
-## Cấu Hình Hạ Tầng
-- Yêu cầu Editor mở cổng debug: `--remote-debugging-port=9555`.
-- Sử dụng `.env` để quản lý `IDE_PORT` đồng nhất với script khởi động.
+## 3. Hệ Thống "Single Brain"
+Bot Telegram không xử lý logic code, nó chỉ là "lễ tân" chuyển tiếp yêu cầu vào Editor. Editor (Antigravity) là thực thể duy nhất nắm giữ bối cảnh và thực thi thay đổi.

package/template/.agent/skills/telegram-agentic-gateway/SKILL.md

@@ -5,83 +5,46 @@ description: Tiêu chuẩn Giao tiếp Telegram (Telegram Gateway) cho các Agen
 
 # KỸ NĂNG: XÂY DỰNG TRẠM ĐIỀU HÀNH TELEGRAM (Telegram Agentic Gateway)
 
-Khi User yêu cầu "Tạo kênh giao tiếp Telegram" hoặc "Làm cho dự án này điều khiển được qua Telegram giống Quản Đốc", bạn (AI) phải thiết kế một `TelegramGateway` tuân thủ nghiêm ngặt **Tiêu chuẩn Giao tiếp lõi** dưới đây.
-
-Một Telegram Gateway chuẩn mực không chỉ là bot chat lăng nhăng, mà phải là một **Trạm Chỉ Huy (Command Center)** với các lệnh System-level.
-
----
-
-## PHẦN A: BỘ LỆNH QUẢN TRỊ CƠ BẢN (Core Management Commands)
-Bất kỳ dự án Agentic nào cũng phải có 4 lệnh sinh tồn sau:
-
-1. **`🚀 /start` (Ping Khởi Động)**
-   - **Tác dụng:** Kiểm tra kết nối xem Lõi AI của dự án có đang thức không. Trả về thông số môi trường hiện tại (Vd: "Bot đang chạy Port 20130, kết nối 9Router ổn định").
-
-2. **`📊 /status` (Camera Giám Sát)**
-   - **Tác dụng:** Liệt kê toàn bộ các Agent (Đặc vụ/Sandbox) ĐANG CHẠY NGẦM trong hệ thống.
-   - **Giao diện:** Phải trả về Inline Keyboard (Nút bấm) ứng với từng Sandbox để User có thể chọc vào xem Log hoặc Tương tác trực tiếp với Agent đó.
-
-3. **`🏭 /spawn <mô_tả>` (Sinh Trực Tiếp Đặc Vụ)**
-   - **Tác dụng:** Ép hệ thống tách 1 luồng độc lập, đẻ ra 1 Sandbox riêng biệt đi làm cái task `<mô_tả>` ở background, không làm kẹt luồng chat hiện tại của User.
-
-4. **`💀 /kill <agent_id>` (Kill-Switch Lệnh Bài Tử thần)**
-   - **Tác dụng:** Lệnh Tối Cao. Nếu một Sandbox chạy tốn token, bị kẹt (loop), hoặc làm sai định hướng, User gõ lệnh này Hệ thống BẮT BUỘC phải force-kill Process/Thread của Agent đó ngay lập tức để giải phóng RAM.
-
----
-
-## PHẦN B: TRÍ NHỚ PHÂN NHIỆM (Topic-Based Memory Isolation)
-Khác lập trình Bot thông thường chỉ lấy `chat.id`, một **Agentic Gateway** tiêu chuẩn BẮT BUỘC phải cô lập trí nhớ dựa trên Telegram Topics (Threads).
-- Nếu User nhắn trong Group Telegram có tính năng Topics: Phải trích xuất `msg.message_thread_id` để làm định danh Ký ức (Vd: `topic-1234.json`).
-- Nếu User nhắn Private: Dùng `chat.id` (Vd: `chat-5678.json`).
-- Nhờ vậy, 1 Group Telegram có thể hoạt động hệt như 1 cái Trello/Kanban Board: Mỗi Topic là 1 Luồng Công Việc riêng biệt, Agent nhớ chính xác bối cảnh của từng file/lỗi đang thảo luận mà không bị chập cheng trí nhớ (Cross-Topic Hallucination).
-
----
-
-## PHẦN C: BỘ LỆNH QUẢN LÝ KÝ ỨC (Cognitive Management)
-Mỗi Topic/Chat trên Telegram sẽ sinh ra 1 File Ký ức lưu Context. Bắt buộc phải có lệnh dọn dẹp cống rãnh:
-
-5. **`🧹 /forget` (Hỏa Thiêu Hồ Sơ)**
-   - **Tác dụng:** Xóa vĩnh viễn File JSON lịch sử chat (Ký ức ngắn hạn) của Topic/Thread hiện tại.
-   - **CẢNH BÁO TỐI THƯỢNG:** Chỉ được phép xóa file JSON Session. TUYỆT ĐỐI KHÔNG ĐƯỢC thiết kế lệnh `/forget` gọi các hàm xóa Vector Database (Ký ức dài hạn dùng chung của dự án) vì sẽ làm toàn bộ Hệ thống Đại Tướng bị mất trí nhớ!
-   - **Bảo mật:** Vì lệnh này mang tính phá hủy dữ liệu, **BẮT BUỘC** phải chặn lại bằng Máy Trạng Thái Cấp Phép (Auth-First) yêu cầu nhập `Password` mới được thi hành.
-
----
-
-## PHẦN D: BỘ LỆNH TIẾN HÓA VÀ CHỮA LÀNH (Self-Healing Mappers)
-Để Dự án có thể tự vá lỗi source code của nó (cần kết hợp với skill `mini-antigravity-injection`), Telegram Gateway phải chứa 2 lệnh Cấp Phép Mổ:
-
-6. **`🏥 /heal <triệu_chứng>` (Tiền Trảm Hậu Tấu)**
-   - **Tác dụng:** Bypass bước duyệt phác đồ.
-   - **Luồng hoạt động:** Nhận lệnh -> Trạng thái chờ Pass -> Nhập Pass đúng -> Cấp quyền (`hasMutationLicense = true`) -> Agent tự tìm Lỗi -> Tự Mổ code -> Tự Test Sandbox -> Tự Hot-reload -> Báo kết quả cuối cùng.
-
-7. **`📋 /healplan <triệu_chứng>` (Khám Bệnh Kê Đơn - Tương Tác)**
-   - **Tác dụng:** Lập phác đồ, cấm chạm vào code thật.
-   - **Luồng hoạt động:** Nhận lệnh -> Trạng thái chờ Pass -> Nhập Pass đúng -> Agent đi khám bệnh -> Nhả ra Phác Đồ + 2 Nút Bấm `[✅ Proceed]` và `[❌ Cancel]`.
-   - User có thể chat qua lại để sửa bản Phác đồ ròng rã cả ngày. Lúc nào ưng ý bấm `Proceed`, Hệ thống bốc Context lôi Agent ra chém đè Code!
-
----
-
-## PHẦN E: GIAO DIỆN PREMIUM (awesome-grammY Aesthetics)
-Một Gateway chuyên nghiệp phải có UI/UX tinh tế:
-1. **Header & Divider**: Sử dụng các thẻ `<b>` và ký tự ngăn cách (e.g. `━━━━━`) để tạo khối thông tin rõ ràng.
-2. **Status Mapping**: Sử dụng emoji trực quan cho trạng thái (✅ Online, 🚨 Offline, 🛡️ Protected).
-3. **Categorized Menus**: Nhóm các nút bấm theo chức năng (Hệ thống, AI, Dự án).
-4. **Short Callback Data**: Vì Telegram giới hạn callback data là 64 bytes, hãy sử dụng `shortIdMap` để lưu trữ Title dài và map chúng với một mã ngắn (e.g. `sess_a1b2`).
-
----
-
-## PHẦN F: KIẾN TẠO HẠ TẦNG & HƯỚNG DẪN (User Setup)
-Khi triển khai, hãy hướng dẫn User:
-1. **Tạo Nhóm (Group with Topics)**: 
-   - Tạo Group Telegram. Thêm Bot làm Admin.
-   - Bật **"Topics"** trong cài đặt nhóm.
-   - Mỗi dự án hoặc tính năng lớn nên là 1 Topic riêng để cô lập ký ức.
-2. **Cấu Hình .env**: Giải thích rõ các token:
-   - `TELEGRAM_BOT_TOKEN`: Lấy từ @BotFather.
-   - `ALLOWED_USER_IDS`: Bảo mật, chỉ cho phép chủ nhân điều khiển.
-   - `IDE_PORT`: Cổng CDP của Antigravity (thường là 9555).
-
----
-
-## TỔNG KẾT TRIỂN KHAI
-*(Ghi chú cho AI)*: Luôn tích hợp VFS (`GEMINI.md`) để tiết kiệm token khi thực hiện code discovery từ xa thông qua Bot.
+Khi User yêu cầu "Tạo kênh giao tiếp Telegram" hoặc "Làm cho dự án này điều khiển được qua Telegram", bạn (AI) phải thiết kế một `TelegramGateway` chuyên nghiệp, tích hợp tinh hoa từ các dự án **Remoat**, **LazyGravity** và framework **grammY**.
+
+## PHẦN A: BỘ LỆNH QUẢN TRỊ SINH TỒN (Core Management)
+Mọi Gateway phải có các lệnh điều khiển hệ thống sau:
+1. **`/start`**: Kiểm tra kết nối, trả về thông số Port (CDP) và trạng thái Bot.
+2. **`/status`**: Liệt kê các Agent/Sandbox đang chạy. Sử dụng Inline Keyboard để tương tác.
+3. **`/stop`**: Dừng khẩn cấp quá trình AI đang sinh code hoặc thực thi (Sử dụng `Page.stopLoading` qua CDP).
+4. **`/screenshot`**: Chụp ảnh màn hình IDE (qua CDP `Page.captureScreenshot`) để giám sát trực quan từ xa.
+
+## PHẦN B: TRÍ NHỚ PHÂN NHIỆM (Topic-Based Isolation)
+Bắt buộc phải cô lập trí nhớ dựa trên **Telegram Topics** (Threads) để chống hiện tượng chập cheng ký ức:
+- Sử dụng `msg.message_thread_id` làm định danh cho file context (Vd: `topic-123.json`).
+- Mỗi Topic trong Group Telegram tương ứng với một luồng công việc/tính năng riêng biệt.
+
+## PHẦN C: QUẢN LÝ MÔ HÌNH & TIẾT KIỆM TOKEN (Model Routing)
+Tích hợp chiến lược chuyển đổi model linh hoạt:
+- **`/model`**: Hiển thị menu chọn Model (Cloud vs Local).
+- **Ưu tiên Local**: Sử dụng **Ollama** cho các tác vụ giải thích hoặc refactor nhỏ để bảo vệ quota Cloud.
+- **VFS Integration**: Luôn tuân thủ giao thức **VFS (Virtual File System)** để tiết kiệm 98% token khi đọc code (Cấu hình tại `GEMINI.md`).
+
+## PHẦN D: PHẪU THUẬT NÃO AI (Self-Healing & Multi-Agent)
+Để dự án tự vá lỗi (kết hợp `mini-antigravity-injection`):
+1. **`/heal`**: Cấp quyền tự mổ (Mutation License).
+2. **`/healplan`**: Yêu cầu Agent lập phác đồ chữa bệnh và chờ lệnh `Proceed` từ User.
+
+## PHẦN E: GIAO DIỆN PREMIUM (grammY Aesthetics)
+Lấy cảm hứng từ `awesome-grammY`:
+- Sử dụng `<b>`, `━━━━━`, và Emoji chuyên nghiệp.
+- **Short Callback Data**: Map ID dài vào `shortIdMap` để bypass giới hạn 64 bytes của Telegram.
+
+## PHẦN F: KIẾN TẠO HẠ TẦNG (Deployment Guide)
+Hướng dẫn User thiết lập:
+1. **Group with Topics**: Tạo Group, thêm Bot làm Admin, bật tính năng Topics.
+2. **Environment**: Cấu hình `.env` khớp với `start.sh` và `stop_bot.sh`.
+   - `IDE_PORT`: Mặc định 9555 (Remote Debugging port).
+   - `ALLOWED_USER_IDS`: Danh sách trắng ID người dùng.
+
+---
+**Nguồn tham khảo & Ảnh hưởng:**
+- [Remoat](https://github.com/optimistengineer/remoat) - Remote Command & Control.
+- [LazyGravity](https://github.com/tokyoweb3/LazyGravity) - Multi-project & Session management.
+- [grammY](https://grammy.dev/) - Modern Bot Framework.
+- [VFS](https://github.com/TrNgTien/vfs) - Virtual File System for Token Efficiency.

package/template/.env.example

@@ -0,0 +1,33 @@
+# 🧠 ANTIGRAVITY GATEWAY CONFIGURATION (.env.example)
+# ----------------------------------------------------------
+
+# [Hạ Tầng Telegram]
+# Lấy token từ @BotFather
+TELEGRAM_BOT_TOKEN="your_bot_token_here"
+
+# ID người dùng được phép điều khiển (Bảo mật - Quan trọng!)
+# Lấy ID qua @userinfobot
+ALLOWED_USER_IDS="123456789,987654321"
+
+# ID Chat/Group được phép hoạt động (Để tránh Bot bị kéo vào group lạ)
+ALLOWED_CHAT_IDS="-100123456789"
+
+# [Cấu Hình IDE]
+# Cổng Debug của Antigravity (Mặc định là 9555)
+# Phải khớp với tham số --remote-debugging-port khi mở Editor
+IDE_PORT=9555
+
+# Tên dự án để Bot tự động tìm kiếm target phù hợp trong CDP
+PROJECT_NAME="ceogravity"
+
+# Đường dẫn Workspace cơ sở (Dùng cho lệnh /project của LazyGravity)
+WORKSPACE_DIR="/home/tao/Projects"
+
+# [Local AI - Ollama]
+# URL của Ollama server (Mặc định: http://localhost:11434)
+OLLAMA_API_URL="http://localhost:11434"
+OLLAMA_MODEL="nemotron"
+
+# [Tùy Chọn Khác]
+LOG_LEVEL="info"
+AUTO_ACCEPT_ENABLED=true

package/template/GEMINI.md

@@ -1,35 +1,35 @@
-# 🚀 Antigravity Core Rules
+# 🚀 Antigravity Core Rules (v1.1.5)
 
-> This file defines the core operational rules for the AI Agent in this workspace.
+> File này định nghĩa các quy tắc vận hành cốt lõi cho AI Agent trong Workspace này.
 
 ---
 
-## 🛠️ TOKEN SAVING: VFS PROTOCOL (MANDATORY)
+## 🛠️ GIAO THỨC TIẾT KIỆM TOKEN: VFS (BẮT BUỘC)
 
-**You MUST use `vfs` for code discovery before using `grep` or reading entire files.**
+**Bạn PHẢI sử dụng `vfs` để khám phá mã nguồn TRƯỚC KHI sử dụng `grep` hoặc đọc toàn bộ nội dung file.**
 
-### Why use VFS?
-`vfs` extracts logical signatures (functions, classes, types) without reading the bodies. This saves up to 98% of tokens compared to raw file reads.
+### Tại sao lại dùng VFS?
+Theo tiêu chuẩn [VFS (Virtual File System)](https://github.com/TrNgTien/vfs), việc trích xuất chữ ký logic (hàm, lớp, kiểu) giúp tiết kiệm đến 98% token so với việc đọc file thô.
 
-### Usage Protocol
-1. **Locate**: Use `vfs search` or `vfs <path>` to find the logical structure.
-2. **Review**: Analyze the signatures returned by `vfs`.
-3. **Read**: Only read the specific line ranges identified via `vfs`.
+### Giao thức sử dụng
+1. **Định vị**: Dùng `vfs search` hoặc `vfs .` để tìm cấu trúc logic.
+2. **Review**: Phân tích các chữ ký (signatures) được trả về.
+3. **Đọc**: Chỉ đọc những dải dòng (line ranges) cụ thể đã được xác định qua VFS.
 
-### Commands
+### Lệnh thực thi
 - **CLI**: `vfs . -f <function_name>`
-- **MCP**: Use the `vfs` MCP tool if available.
+- **MCP**: Sử dụng công cụ `vfs` nếu có sẵn trong bộ skill.
 
 ---
 
-## 🤖 MODEL SELECTION
+## 🤖 CHIẾN LƯỢC CHỌN MÔ HÌNH (MODEL SELECTION)
 
-- **Simple Tasks**: Prefer local Ollama models (e.g., `nemotron`, `llama3`) to save cloud budget.
-- **Complex Tasks**: Use high-tier models (e.g., `Claude 3.5 Sonnet`, `Gemini 1.5 Pro`).
+- **Tác vụ đơn giản**: Ưu tiên sử dụng mô hình Local qua **Ollama** (Vd: `nemotron`, `llama3`) để tiết kiệm chi phí cloud.
+- **Tác vụ phức tạp**: Sử dụng các mô hình cao cấp (Vd: `Claude 3.5 Sonnet`, `Gemini 1.5 Pro`).
 
 ---
 
 ## 🧹 CLEAN CODE
-- Write self-documenting code.
-- Avoid over-engineering.
-- Follow the patterns defined in `.agent/skills/clean-code`.
+- Viết mã tự giải thích (Self-documenting).
+- Tránh Over-engineering.
+- Tuân thủ các pattern định nghĩa trong `.agent/skills/clean-code`.

package/template/start.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# 🧠 ANTIGRAVITY STARTUP SCRIPT (Standard v1.1.5)
+# --------------------------------------------------
+# Script này khởi động Antigravity Bot với cấu hình từ .env
+
+# 1. Load configuration
+if [ -f .env ]; then
+  export $(grep -v '^#' .env | xargs)
+else
+  echo "❌ Lỗi: Không tìm thấy file .env. Vui lòng tạo từ .env.example"
+  exit 1
+fi
+
+# 2. Defaults
+IDE_PORT=${IDE_PORT:-9555}
+PROJECT_NAME=${PROJECT_NAME:-"ceogravity"}
+
+echo "🚀 Đang khởi động Antigravity Gateway..."
+echo "📂 Dự án: $PROJECT_NAME"
+echo "🔌 Cổng Debug: $IDE_PORT"
+
+# 3. Start Bot (Sử dụng tsx để chạy TypeScript trực tiếp)
+# Ghi chú: Đảm bảo Antigravity IDE đã được mở với --remote-debugging-port=$IDE_PORT
+npx tsx src/index.ts

package/template/stop_bot.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# 🛑 ANTIGRAVITY STOP SCRIPT (Standard v1.1.5)
+# --------------------------------------------------
+
+# Tìm và giết các tiến trình liên quan đến bot
+echo "🛑 Đang dừng Antigravity Gateway..."
+
+# Tìm PID của tsx src/index.ts
+PIDS=$(pgrep -f "tsx src/index.ts")
+
+if [ -z "$PIDS" ]; then
+  echo "⚠️ Không tìm thấy tiến trình Bot đang chạy."
+else
+  kill $PIDS
+  echo "✅ Đã dừng Bot (PIDs: $PIDS)"
+fi