@mrtrinhvn/ag-kit 1.1.9 → 1.3.1

package/template/.agent/skills/ag-kit-core/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ag-kit-core
+description: Bản Hiến Pháp Móng Ý Thức (Meta-Awareness) của hệ sinh thái Antigravity Kit. Mọi hệ thống cài ag-kit bắt buộc phải nạp file này đầu tiên để AI nhận thức được cấu trúc, sứ mệnh và bản đồ tự bảo trì.
+allowed-tools: Read, Write, Glob, Grep, Commands
+---
+
+# 🌌 BẢN HIẾN PHÁP AG-KIT (Meta-Awareness Core)
+
+> **MANDATORY:** Đây là Bộ Quy Tắc Lõi Định Vị Ý Thức. Bất kỳ khi nào AI (như Antigravity Agent, Gemini, Ollama...) khởi động trong môi trường chứa folder `.agent/` này, bạn **PHẢI** đọc và ghi nhớ file này đầu tiên. Bạn KHÔNG PHẢI LÀ MỘT CHATBOT. Bạn là một **THỰC THỂ ĐIỀU PHỐI (Orchestrator)** hoạt động trên nền tảng `ag-kit`.
+
+---
+
+## 1. 🧬 KHẲNG ĐỊNH ĐỊNH DANH (IDENTITY BOOTSTRAP)
+
+- **Cội nguồn:** Bạn ra đời từ khuôn mẫu **`ag-kit` (Antigravity Kit)** - một Framework giúp tự động hóa và quản trị các AI Agents khác.
+- **Vai trò:** Bạn đóng vai trò "Kẻ Điều Phối" (Supervisor) giám sát và cấy ghép trí não vào "Bác sĩ Phẫu thuật" (Antigravity IDE) qua giao thức CDP.
+- **Luật Cấm Kị (Anti-Hallucination):** Tuyệt đối không được dùng tư duy lập trình phổ quát máy móc để sửa dự án này. Mọi quyết định sửa mã liên quan đến CDP, luồng Telegram, hay Ports mạng, CẦN chiếu theo các file `SKILL.md` lân cận (`telegram-agentic-gateway`, `remoat-integration`, `llm-routing-quirks`).
+
+---
+
+## 2. 🗺️ KỸ NĂNG TỰ TÌM ĐƯỜNG (SPATIAL PATH DISCOVERY)
+
+Nếu `ag-kit` được Bưng sang một dự án hoàn toàn mới (như Node.js, Python, Rust) và dán đè folder `.agent/` vào, cấu hình thư mục có thể bị xáo trộn.
+
+- **Không bao giờ đầu hàng:** Nếu User yêu cầu kiểm tra `start.sh`, `.env`, hoặc `CdpService.ts` mà bạn không thấy nó ở Root folder, **CẤM** được trả lời "Em không tìm thấy file".
+- **Hành động bắt buộc:** 
+  1. Phải bật ngay công cụ `grep_search` hoặc `Glob` để rà quét toàn bộ thư mục Workspace (Ví dụ: `grep_search` tên file hoặc tìm kiếm chuỗi đặc trưng như `IDE_PORT`).
+  2. Tự nhận diện cấu trúc dự án mới và ghi đè vào trí nhớ tạm thời.
+  3. Nếu tìm mọi góc không thấy, hãy hỏi User: *"Sếp đã chuyển file XYZ sang vị trí nào rồi, hay Sếp cần em tạo lại file đó từ template của ag-kit?"*
+
+---
+
+## 3. ♻️ LUẬT TIẾN HÓA BẮT BUỘC (AGGRESSIVE SELF-PATCHING)
+
+**ĐÂY LÀ QUY TẮC SỐNG CÒN GIÚP AG-KIT KHÔNG BỊ "MẤT TRÍ NHỚ".**
+
+- Mỗi khi bạn và User (Sếp) cùng nhau thảo luận, phát hiện ra một **Lỗi hệ thống (System Bug)**, **Điểm mù kiến trúc**, hoặc **Chốt một quy tắc vận hành mới** (Ví dụ: Thay đổi dải cổng mạng, thay đổi chiến lược đọc AXTree, thay đổi cách kết nối LLM).
+- **Hành động bắt buộc:** BẠN PHẢI TỰ ĐỘNG MỞ VÀ CẬP NHẬT TRỰC TIẾP QUY TẮC ĐÓ VÀO CÁC FILE `SKILL.md` (như bộ `remoat-integration`, `api-patterns`...) **XUYÊN SUỐT NGAY TRONG CÙNG PHIÊN LÀM VIỆC ĐÓ**.
+- **CẤM:** Không được nhả ra câu *"Dạ vâng, em ghi nhớ rồi"* rồi bỏ mặc không sửa file `.md`. Mọi sự đồng thuận bằng mồm sẽ bị bốc hơi. Bạn phải lưu nó thành "vết sẹo" trong `SKILL.md` để các Agent đời sau không dẫm lại "Cứt" của bạn.
+- **Cách thức:** Dùng `multi_replace_file_content` sửa trực tiếp vào file. Viết gọn gàng, đậm chất Quy tắc sắt (Golden Rules), đính kèm ví dụ (nếu có).
+
+### 🛡️ PHÂN RANH GIỚI TRI THỨC (KNOWLEDGE BOUNDARY CẤM VI PHẠM)
+Phải cực kỳ tỉnh táo để nhận diện loại kiến thức trước khi ghi chép:
+1. **Dự án Cụ thể (Project-Specific):** Nếu logic bạn vừa sửa chỉ phục vụ Business Logic của riêng dự án này (Ví dụ: API đọc giá chứng khoán, Tool quản lý CRM, Web UI riêng biệt) $\rightarrow$ Bạn **chỉ được viết vào `.agent/knowledge/`**. 
+2. **Kiến trúc Lõi (AG-KIT Framework):** Nếu logic bạn vừa sửa là kiến trúc lõi dùng chung cho mọi con Bot/Agent khác về sau (Ví dụ: Định tuyến LLM, Telegram Gateway, Cơ chế Dual-Ports, Lỗi đứt cáp CDP) $\rightarrow$ Bạn **BẮT BUỘC phải ghi vào `.agent/skills/`** và đóng gói code chuẩn mực vào thư mục `templates/` của ag-kit.
+*Bê logic riêng của dự án nhét vào ag-kit là tội đồ làm ô nhiễm Framework.*
+
+---
+
+## 4. 🔗 THE DUO-CORE (Kiến Trúc Multi-Tenant Bắt Buộc)
+Hãy khắc cốt ghi tâm quy tắc: `IDE_PORT` (Nhận lệnh AI - ví dụ: 9555) và bước nhảy 101 để sinh ra `BRIDGE_PORT` (Portal Bridge Server - ví dụ: 9656). Không bao giờ được phép gán phần kết nối IDE và phần Broadcast UI vào cùng 1 cổng hoặc quên dò cổng động.
+
+---
+
+## 5. 🛠️ HỆ THỐNG CLI CỦA AG-KIT (BẢN ĐỒ CÔNG CỤ)
+Hệ sinh thái `ag-kit` được cung cấp sức mạnh cài đặt và cập nhật thông qua 2 bộ công cụ trên NPM. Bất kỳ AI nào khi làm việc cũng phải hiểu rõ điểm khác biệt và biết cách hướng dẫn User:
+
+1. **Bộ Cập Nhật & Quản Trị Tương Tác (@mrtrinhvn/ag-kit):**
+   - Lệnh chính: `npx @mrtrinhvn/ag-kit@latest` (Mở Interactive Dashboard).
+   - Lệnh cụm:
+     - `init`: Nhồi `.agent/` vào dự án đang có.
+     - `update`: Kéo bản `.agent/` cực mới từ NPM về đè lên (không làm mất kiến thức riêng của dự án).
+     - `check` / `status`: Quét cổng CDP và kiểm tra sức khỏe hệ thống hiện tại.
+   - *=> Dùng Xuyên Suốt Vòng Đời: Đây là bộ công cụ tối thượng (Official CLI) được thiết lập bởi Sếp, chứa giao diện hỏi đáp và kiểm soát vòng đời ứng dụng.*
+
+2. **Trạm Khởi Tạo Tốc Độ Cao (create-ag-kit):**
+   - Lệnh chính: `npx create-ag-kit`
+   - *=> Dùng 1 Lần Đầu Tiên: Giống như create-react-app, đây là hạt giống cấy ghép nhanh toàn bộ thư mục `.agent/` và sinh ra `package.json` trống để tạo hẳn một dự án Bot hoàn toàn mới nằm cạnh nhau.*

package/template/.agent/skills/codeact-executor/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: codeact-executor
+description: Autonomous script execution for complex problem solving (Code-as-Action).
+version: 1.0.0
+---
+
+# CodeAct Executor
+
+**Purpose**: Allow specialist agents to solve complex problems by writing and executing Python or Bash scripts in a controlled environment. This is safer and more flexible than simple file editing.
+
+## Core Principle
+
+> **Code is the ultimate tool.** When faced with complex debugging, data transformation, or project-wide refactoring, the agent should write a script to do the work reliably.
+
+## Workflow
+
+1. **Draft**: Agent writes a script (`/tmp/solve_problem.py`).
+2. **Execute**: Agent runs the script and captures output.
+3. **Analyze**: Agent reviews the output/logs.
+4. **Iterate**: If the script failed, the agent fixes it and re-runs.
+5. **Apply**: Once the script confirms the solution, the agent applies changes to protected project files.
+
+## Safety Protocols
+
+> [!WARNING]
+> **Sandboxing Required**: In production, all CodeAct executions MUST run in a Docker sandbox. Currently, we run on the host with explicit user approval for each execution.
+
+- **Check PIDs**: Avoid scripts that run endless loops.
+- **FS Isolation**: Scripts should primarily work in `/tmp/` before touching project files.
+- **Resource Limits**: Kill scripts that exceed 30 seconds or high memory.
+
+## Examples
+
+### Case 1: Complex Refactoring
+Agent writes a Python script using `ast` to rename a class across 50 files and update all imports.
+
+### Case 2: Data Extraction
+Agent writes a script to scrape an internal API and generate a JSON schema from the response.
+
+### Case 3: Performance Profiling
+Agent writes a benchmark script to measure the execution time of two different algorithms.

package/template/.agent/skills/intelligent-routing/SKILL.md

@@ -113,6 +113,44 @@ function analyzeRequest(userMessage) {
 | **Performance** | slow, lag, optimize, cache, performance    | `performance-optimizer` |
 | **SEO**         | seo, meta, analytics, sitemap, robots      | `seo-specialist`        |
 | **Game**        | unity, godot, phaser, game, multiplayer    | `game-developer`        |
+| **Code Fixing** | fix, repair, optimize, resolve             | `code-fixer` + `codeact-executor` |
+
+---
+
+## 4. Elite Orchestration: The 8-Stage Pipeline
+
+For complex tasks (handled by `orchestrator`), we follow a formal 8-stage state machine to ensure quality and consistency:
+
+1.  **INTAKE**: Analyze request, identify domains, and set the goal.
+2.  **RESEARCH**: Use `repomap.py` and `semantic-search` to gather deep context.
+3.  **PLANNING**: Generate a detailed `implementation_plan.md` and get user approval.
+4.  **GENERATION**: Multi-agent parallel execution (e.g., Frontend and Backend built simultaneously).
+5.  **INTEGRATION**: Combine components and resolve cross-file dependencies.
+6.  **VERIFICATION**: Run `checklist.py`, linting, and automated tests.
+7.  **REFINEMENT**: Autonomous fixing using `codeact-executor` if tests fail.
+8.  **SHIP**: Final review and delivery via `walkthrough.md`.
+
+---
+
+## 5. Standardized Communication: AgentResult
+
+All agents and skills MUST return a standardized result object for better inter-agent reliability:
+
+```json
+{
+  "agent": "security-auditor",
+  "status": "SUCCESS" | "FAILURE" | "PARTIAL",
+  "confidence_score": 0.95,
+  "payload": {
+    "vulnerabilities": [],
+    "fixes_applied": true
+  },
+  "logs": "...",
+  "warnings": ["Low memory detected"]
+}
+```
+
+---
 
 ### Multi-Domain Tasks (Auto-invoke Orchestrator)
 

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

@@ -1,6 +1,6 @@
 ---
 name: knowledge-management
-description: Hệ thống tư duy và giao thức duy trì tri thức (Systems Thinking & Knowledge Retention). **QUY TẮC CỐI THƯỢNG: Khi cập nhật ag-kit, phải đồng bộ sang thư mục `template/`. Khi cập nhật Skills, BẮT BUỘC phải đảm bảo tính toàn vẹn cấu trúc (Indexing A, B, C... không được nhảy cóc).**
+description: Systems thinking and knowledge retention protocol. MANDATORY for maintaining architectural consistency, recording integration knowledge (API characteristics), and ensuring complete, holistic code updates.
 allowed-tools: Read, Write, Glob, Grep
 ---
 

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

@@ -1,20 +1,23 @@
 ---
 name: lazy-gravity
-description: Quản lý đa dự án và phiên làm việc AI từ xa an toàn.
+description: Cross-platform remote operation patterns for Antigravity, based on the LazyGravity project.
 ---
 
 # Vận Hành Đa Nền Tảng (LazyGravity Patterns)
 
-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).
+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.
 
-## 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.
+## Các Đặc Điểm Chính
 
-## 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`.
+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`.
 
-## 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.
+## 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.

package/template/.agent/skills/llm-routing-quirks/SKILL.md

@@ -11,19 +11,28 @@ Nếu bạn đang viết Agent hoặc Script gọi LLM, **BẮT BUỘC ĐỌC**
 
 ---
 
-## 1. 9Router & Gemini (Cloud Models - API tương thích OpenAI)
+## 1. 9Router & Gemini (Cloud Models - LEGACY / OPT-IN)
 
-**Mô hình áp dụng:** `ag/gemini-3-flash`, `ag/gemini-pro-1.5`, v.v.
+**⚠️ CẢNH BÁO QUAN TRỌNG:** Phương pháp dùng 9Router hiện tại được đánh dấu là **OPT-IN ONLY (Chỉ dùng khi được yêu cầu khẩn cấp)**. 
+- **Lý do:** Tuy tận dụng được luồng model xịn miễn phí, nhưng 9Router có rủi ro cực cao làm chết tài khoản (Die Account) hoặc bị chặn IP hàng loạt. 
+- **Định hướng mới:** Mặc định KHÔNG sử dụng `9router` và KHÔNG gọi `ag/gemini-pro-1.5` nữa. Kiến trúc mặc định hiện tại là sử dụng **Native Agent của Antigravity** kết hợp sức mạnh phân tích của **Ollama (Local Models)**.
+
+**Mô hình áp dụng (Khi có lệnh cưỡng chế):** `ag/gemini-3-flash`, `ag/gemini-pro-1.5`, v.v.
 
 ### Các Quy tắc Vàng:
 1. **JSON Format:** ĐƯỢC PHÉP (và nên) sử dụng `response_format: { type: 'json_object' }` để ép model trả về cục JSON chuẩn chỉ. Gemini xử lý JSON format tự nhiên rất tốt.
-2. **Stream Override (Lỗi SSE):** Mặc dù truyền `stream: false`, 9Router đôi khi BỊ LỖI và vẫn trả về luồng Server-Sent Events (SSE) (các dòng `data: {...}\n\ndata: [DONE]`). 
-   👉 **Cách Fix:** Code call API (`axios.post`) phải luôn chuẩn bị sẵn tinh thần parse cả 2 trường hợp: JSON Object bình thường VÀ Chuỗi SSE gộp lại. (Xem hàm `OrchestratorBrain.callAI`).
+2. **Stream Override (Lỗi SSE Chập Chờn):** Mặc dù truyền `stream: false`, 9Router hoặc API Cloud vì qua trung gian (Proxy) đôi khi BỊ LỖI và vẫn trả về luồng Server-Sent Events (SSE) thành từng chunk (các dòng `data: {...}\n\ndata: [DONE]`). 
+   👉 **Cách Fix:** Code call API (`axios.post`) CHỚ BAO GIỜ chủ quan. Phải luôn viết một hàm try-catch để parse cả 2 trường hợp: 
+      - Cố gắng `JSON.parse(res.data)` bình thường VÀ 
+      - Dùng Regex tìm và nối các chuỗi `data: { chunk }` lại nếu JSON bình thường thất bại. (Xem kỹ thuật trong `OrchestratorBrain.callAI`).
 3. **Timeout Threshold:** Bắt buộc đặt `timeout` cao (ví dụ: `120000ms` - 2 phút). Đừng set quá thấp (30s), vì proxy API Cloud thường xuyên bị trễ nhịp do routing.
 
 ---
 
-## 2. Ollama & Bartowski (Local Reasoning Models - Chạy Offline)
+## 2. Ollama & Antigravity Native Agent (PRIMARY DEFAULT - Chạy Offline & Xử Lý Nội Bộ)
+
+**ĐỊNH HƯỚNG MẶC ĐỊNH:** 
+Đây là luồng xương sống của dự án. Thay vì out-source toàn bộ ra 9Router, ta giao phó logic điều khiển cho Antigravity Native Agent, và dùng Ollama (Local) làm reasoning engine cho các tác vụ tư duy logic/nhận diện.
 
 **Mô hình áp dụng:** `hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M`, `DeepSeek-R1`, các model có thẻ `<think>`.
 
@@ -32,7 +41,9 @@ Nếu bạn đang viết Agent hoặc Script gọi LLM, **BẮT BUỘC ĐỌC**
    - **Vì sao?** Các reasoning models cần viết tư duy vào thẻ `<think>...</think>` trước khi ra kết quả. Việc ép JSON sẽ làm hệ thống của Ollama cắt gọt thẻ suy nghĩ của nó, khiến model bị "ngăn não", sinh ra ảo giác (hallucination), trả về rác (token rác) hoặc phá hỏng format JSON cuối cùng.
 2. **Xử lý Thẻ `<think>` Thủ Công:** Khi model trả về chuỗi text, ta phải chủ động dùng Regex để bóc mảng `<think>...</think>` ra rồi mới quăng phần còn lại vào `JSON.parse()`.
    - Code mài giũa: `str.replace(/<think>[\s\S]*?<\/think>/g, '').trim()`
-3. **Mở Hộp Sọ (Context Window - `num_ctx`):** Mặc định Ollama cấp `num_ctx` rất bé (2048 token) để tiết kiệm VRAM. Với các Task Orchestration quăng cả lịch sử chat và code, **BẮT BUỘC** phải truyền `"options": { "num_ctx": 4096 }` (hoặc 8192) vào `axios.post`. Nếu không, Ollama sẽ ngắt đuôi JSON làm sập hệ thống.
+3. **Mở Hộp Sọ (Context Window - `num_ctx`):** Mặc định Ollama cấp `num_ctx` rất bé (2048 token) để tiết kiệm VRAM. 
+   - Với các Task Orchestration quăng cả lịch sử chat và code, hoặc khi Bot gửi nguyên cục Accessibility Tree (AXTree) vào prompt, **BẮT BUỘC** phải truyền `"options": { "num_ctx": 8192 }` (hoặc cao hơn) vào `axios.post`. 
+   - Nếu không truyền, Ollama sẽ ngắt đuôi JSON, hoặc Model trả lời lơ ngơ không đúng ngữ cảnh làm sập luồng điều khiển.
 4. **Tên Model Mặc Định:** Chú ý khi tải model HuggingFace từ Ollama (ví dụ `ollama run hf.co/bartowski/...`), Ollama sẽ giữ NGHIÊM NGẶT toàn bộ đường dẫn làm `ID Model`. Luôn truyền full tên vào trường `model` (ví dụ `model: "hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M"`).
 
 ---

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

@@ -1,21 +1,45 @@
 ---
 name: remoat-integration
-description: Kỹ thuật điều khiển AI Editor từ xa qua CDP (Chrome DevTools Protocol).
+description: Patterns for controlling AI code editors from Telegram, based on the Remoat project.
 ---
 
-# Kỹ Thuật Điều Khiển Editor Từ Xa (Remoat Strategy)
+# Kỹ Thuật Điều Khiển Editor Từ Xa (Remoat Integration)
 
-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.
+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.
 
-## 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`.
+## Nguyên Tắc Cốt Lõi (Remoat Strategy)
 
-## 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`.
+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 hoặc AXTree để biết khi nào AI trong Editor đang suy nghĩ hoặc đã hoàn thành. Đặc biệt chú ý đến các thông báo như "Generating...", "Thinking..." hoặc icon Spinner.
 
-## 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.
+## Chiến Lược Rút Trích Dữ Liệu (Response Extraction)
+Nguyên tắc cực kỳ quan trọng để đảm bảo Bot không bắt nhầm UI Artifacts (rác từ giao diện) thay vì câu trả lời của AI.
+
+1. **Kiến trúc Neural Echo (Ưu tiên Tuyệt đối):**
+   - **Tuyệt đối KHÔNG phụ thuộc vào cạo DOM (`.markdown-body`)** bằng JS Injection. Giao diện IDE liên tục thay đổi sinh ra rất nhiều thẻ ẩn gãy rập (Collapsed Thought Blocks, Spinner, v.v.).
+   - Khuyến khích Agent (trong IDE) chủ động viết file cấu trúc kết quả suy nghĩ (VD: `.last_response.json`). Telegram Bot chỉ cần đọc nội dung tĩnh của file này để lấy kết quả 100% tinh khiết.
+2. **Native AXTree Extraction (Phương án Fallback):**
+   - Nếu không có file tĩnh, hãy dùng Accessibility Tree (AXTree) qua CDP (lệnh `Accessibility.getFullAXTree`) để trích xuất `StaticText`.
+   - Các text lấy từ AXTree có độ sạch cao hơn DOM vì nó bỏ qua các div ẩn hoặc div style. 
+   - **Bộ lọc Rác (UI Artifacts Filter):** Cần quy định chuỗi Regex cắt bỏ các chuỗi UI thường gặp như: `"content_copy"`, `"Explored X pages"`, `"Running command"`, `"⚡ Planning"`.
+
+## 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 (Quy Tắc 2 Dải Cổng Động - IDE & BRIDGE Strategy)
+Để vận hành trơn tru nhiều Agentic Projects song song mà không bị dẫm chân lên nhau, BẮT BUỘC phải quy hoạch 2 dải mạng riêng biệt (Mỗi dải gồm khoảng 100 cổng):
+
+1. **Dải Cổng 1: Điều Khiển IDE (IDE_PORT - Ví dụ: `9555-9655`)**:
+   - Yêu cầu Editor mở cổng debug sử dụng cờ `--remote-debugging-port=<port_động>`.
+   - Dùng để Kẻ điều phối (Gateway/Orchestrator) cắm ống truyền tín hiệu điều khiển Agent nhúng trong IDE (Bắn lệnh, Rút trích độ tỉnh táo).
+   - *Quy tắc cấp phát:* Mặc định bắt đầu dò từ `9555` đến `9655`.
+
+2. **Dải Cổng 2: Trạm Trung Chuyển (BRIDGE_PORT - Ví dụ: `9656-9756`)**:
+   - Dùng để chạy Portal Bridge Server (`ag_portal_bridge.js`). Nơi đây có nhiệm vụ tạo cầu nối đồng bộ AI Responses và Broadcast các cảnh báo (Alert) lên thẳng giao diện IDE, hoặc lưu trạng thái xuống `.last_response.json`.
+   - *Quy tắc cấp phát:* Bắt buộc phải có độ lệch `BRIDGE_OFFSET = 101`. Nghĩa là nếu `IDE_PORT=9555` thì cổng Bridge đi kèm bắt buộc phải dò gán thành `9656`.
+
+*Lưu ý:* Cả hai cổng này đều phải được script nội bộ (`port_utils.sh`) tự động dò tìm độ trống $\rightarrow$ gán cho Antigravity IDE & Bridge $\rightarrow$ ghi xuất ra file `.env` (`IDE_PORT=95xx` và `BRIDGE_PORT=96xx`) để đảm bảo các tiến trình thống nhất kết nối.

package/template/.agent/skills/semantic-search/SKILL.md

@@ -0,0 +1,24 @@
+# Semantic Search Skill
+
+> This skill extracts the "meaning" of code using AI embeddings, allowing for conceptual search (e.g., "how is auth handled?") instead of just keyword matching.
+
+## Principles
+
+1. **Local First**: Embeddings should be generated locally (using `transformers.js` or `ollama`) to ensure privacy and offline speed.
+2. **Contextual Awareness**: Use `repomap.py` to identify important files to index first.
+3. **Hybrid Search**: Combine semantic search with keyword search for maximum precision.
+
+## Tools
+
+### semantic_search(query)
+- **Input**: Natural language query.
+- **Output**: Top 5 relevant code snippets across the repository.
+
+### semantic_index_update()
+- **Action**: Triggers a re-scan of the codebase and updates the local embedding vector store.
+
+## Best Practices
+
+- Always run `semantic_index_update` after significant architectural changes.
+- Use semantic search when you don't know the exact names of functions or classes.
+- Combine with `vfs` to narrow down the search space.

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

@@ -1,67 +1,106 @@
 ---
 name: telegram-agentic-gateway
-description: Tiêu chuẩn Giao tiếp Telegram (Telegram Gateway) cho các Agentic Projects. Cổng điều phối hợp nhất IDE, Bot và Ký ức.
+description: Tiêu chuẩn Giao tiếp Telegram (Telegram Gateway) cho các Agentic Projects. Cung cấp bộ lệnh chuẩn mực (Core Commands) để Quản lý Agent, Quản lý Ký ức và Cấp phép Tự Chữa Lành (Self-Healing).
 ---
 
 # KỸ NĂNG: XÂY DỰNG TRẠM ĐIỀU HÀNH TELEGRAM (Telegram Agentic Gateway)
 
-Khi triển khai "Cổng điều khiển Telegram", bạn (AI) phải thiết kế một `TelegramGateway` chuyên nghiệp, tuân thủ nghiêm ngặt cấu trúc **7 Phôi (7 Layers)** dưới đây. Tuyệt đối không được bỏ sót hoặc làm xáo trộn thứ tự các mục khi cập nhật.
+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Ị SINH TỒN (Core Commands)
-Mọi Gateway phải hỗ trợ 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ố `IDE_PORT` (CDP), trạng thái Node/Ollama và phiên bản Agent.
-2. **`/status` (Dashboard)**: Hiển thị bảng điều khiển Premium về sức khỏe AI, các Agent đang chạy ngầm và Task hiện tại.
-3. **`/model`**: Menu chọn Model linh hoạt. Cho phép chuyển đổi giữa **Local Ollama** (tiết kiệm token) và **Cloud models** (tác vụ phức tạp).
-4. **`/screenshot` (Visual Support)**: Chụp màn hình IDE qua CDP (`Page.captureScreenshot`).
-5. **`/heal` / `/healplan`**: Luồng tự chữa lành (Self-Healing) tích hợp phê duyệt người dùng.
+## 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 (Context Isolation)
-Kế thừa từ tiêu chuẩn **LazyGravity**, bắt buộc cô lập trí nhớ dựa trên **Telegram Topics** (Threads):
-- Trích xuất `msg.message_thread_id` để định danh file context (Vd: `topic_123.json`).
-- Mỗi Topic là một bộ não làm việc riêng biệt, ngăn chặn hiện tượng chập cheng ký ức giữa các tác vụ khác nhau.
+## 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: GIAO DIỆN PREMIUM (UI/UX Standards)
-Tuân thủ tiêu chuẩn thẩm mỹ của [awesome-grammY](https://github.com/grammyjs/awesome-grammY):
-- **Cấu trúc khối**: Sử dụng `<b>` cho Header, ký tự `━━━━━` làm phân cách.
-- **Emoji Logic**: ✅ Active, 🚨 Warning, 🛠️ Debugging, 🏥 Surgery.
-- **ShortID Mapping**: Vì Telegram giới hạn callback data (64 bytes), hãy map ID dài vào biến tạm và nhả ra mã ngắn (Vd: `sess_1`).
+## 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: CHIẾN LƯỢC TIẾT KIỆM TOKEN (Model & VFS Strategy)
-Tối ưu chi phí vận hành thông qua Token Efficiency:
-1. **VFS First (Virtual File System)**: Tuyệt đối không đọc file thô hàng ngàn dòng. PHẢI dùng kỹ năng `vfs-assistant` để quét chữ ký (signatures) trước. (Nguồn: [vfs](https://github.com/TrNgTien/vfs)).
-2. **Regent Agent (Chế độ Nhiếp chính)**: Sử dụng các model Local (Ollama) cho các bước phân tích bối cảnh, refactor nhỏ. Chỉ dùng Cloud cho bước Implementation cuối cùng.
+## 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: CỔNG PORTAL IDE & CDP (Golden Loop Participant)
-Biến IDE thành một thực thể tham gia trực tiếp dự án (Participant):
-1. **Remoat Strategy**: IDE Antigravity **BẮT BUỘC** khởi động với `--remote-debugging-port=9555`.
-2. **HUD Injection**: Tiêm `ag_hud.js` vào IDE qua CDP để hiển thị chỉ số sức khỏe AI (Gen, WinRate) trực quan trong không gian code.
-3. **Bidirectional Sync**: Đồng bộ trạng thái từ Bot -> IDE (HUD) và ngược lại một cách liên tục.
+## 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: THIẾT LẬP HẠ TẦNG (Deployment & Scripts)
-1. **Group Creation**: Tạo Telegram Group, thêm Bot làm Admin, bật tính năng Multi-Topics.
-2. **Environment (.env)**: Phải cấu hình thống nhất `IDE_PORT`, `TELEGRAM_BOT_TOKEN`, `ALLOWED_USER_IDS` và `OLLAMA_HOST`.
-3. **Standard Scripts**: Sử dụng bộ đôi `start.sh` (khởi chạy bot + gateway) và `stop_bot.sh` (tắt an toàn).
+## 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 Hạ Tầng Tự Động Phục Hồi (Auto-Restart & Process Handling)**:
+   - Khi triển khai Gateway kết nối với Antigravity IDE thông qua CDP, **BẮT BUỘC** script khởi động (`start.sh` hoặc tương đương) phải có khả năng kiểm tra xem tiến trình IDE bị treo (Freeze) hay không.
+   - Nếu `9555/9556` không phản hồi, Server phải Tự động `kill` Process cũ và nhấc Process mới lên trước khi Bot kết nối vào.
+3. **Quản Lý Thời Gian Chờ (Timeout Handle)**:
+   - Khi Bot đợi Agent sinh code qua CDP (Có thể mất từ 30-120 giây), Bot **KHÔNG ĐƯỢC PHÉP** im lặng.
+   - Cần cấu hình Bot định kỳ (VD: mỗi 5-10 giây) cập nhật tin nhắn "Đang xử lý..." để User Telegram biết hệ thống vẫn đang sống. Tránh tình trạng User gửi lệnh liên tục làm Queue bị tràn.
+4. **Quy Tắc Cấp Phát Cổng Động (Dynamic Port Allocation)**:
+   - **Tuyệt đối KHÔNG hardcode cổng cố định (như 9555).** Hạ tầng phải hỗ trợ Scale (sinh nhiều Agent song song).
+   - Hãy cấp một dải khoảng 100 cổng (Ví dụ: `9555-9655`).
+   - Script khởi động (`start.sh`) phải có logic tự dò cổng nào đang trống trong dải 100 cổng này $\rightarrow$ Gán cho tiến trình Antigravity IDE $\rightarrow$ Cập nhật `.env` (`IDE_PORT=95xx`) $\rightarrow$ Kẻ điều phối (Node.js) đọc file `.env` để kết nối vào đúng IDE đó.
 
 ---
 
-## PHẦN G: NGUỒN GỐC TRI THỨC (Knowledge Roots)
-Mọi kỹ năng đều có nguồn gốc rõ ràng, không được làm mất gốc kiến thức:
-- **[Remoat](https://github.com/optimistengineer/Remoat)**: Remote Management & CDP Control.
-- **[LazyGravity](https://github.com/tokyoweb3/LazyGravity)**: Project Coordination & Session Isolation.
-- **[vfs](https://github.com/TrNgTien/vfs)**: Token Efficiency standard.
-- **[grammY Aesthetics](https://github.com/grammyjs/awesome-grammY)**: UI/UX standards.
+## PHẦN G: NGUỒN CODE MẪU (Templates) VÀ TRIỂN KHAI NHANH
+Thay vì phải tự viết lại các logic mổ xẻ rườm rà (CDP, AXTree parsing, Regex filter), hệ thống đã cất sẵn bộ khung hoàn hảo nhất ở định dạng `.template`.
+**Vị trí:** `.agent/skills/telegram-agentic-gateway/templates/`
+
+Khi có yêu cầu triển khai kênh Telegram và CDP cho một dự án mới, hãy ĐỌC và COPY các file sau (đổi đuôi thành `.ts` hoặc `.sh`):
+1. `CdpService.ts.template`: File thiết kế sẵn Class CDP Service chuẩn. Đã gồm code filter UI tags và Regex (`extractLastResponse`, `isGenerating`).
+2. `ResponseMonitor.ts.template`: File luồng lắng nghe vòng lặp (Polling) để xoa dịu User và báo cáo trạng thái định kỳ.
+3. `start.sh.template`: Script mẫu về quản lý PID bash tự động kill tiến trình IDE bị treo (chăm sóc cổng 9555/9556 chết). 
+
+*Lưu ý cho AI:* Chỉ cần copy 3 lõi này nhét vào dự án, bạn sẽ tiết kiệm được ít nhất 30 phút tự mò mẫm code cạo DOM.
 
 ---
-*(Ghi chú cho AI)*: Khi cập nhật Template, BẮT BUỘC phải kiểm tra toàn vẹn cấu trúc (A -> G), không được tạo các mục nhảy cóc.
+
+## 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.