@mrtrinhvn/ag-kit 1.1.1 → 1.1.3

package/README.md

@@ -1,78 +1,75 @@
 # Antigravity Kit Core (`@mrtrinhvn/ag-kit`) 🚀
 
-A generic, institutional-grade AI programming framework for automating scaffolding, architecture, and coding directly inside your software projects. Inspired by the principles of `.agent` systems, carefully stripped of domain-specific constraints to adapt to any software development lifecycle.
+A generic, institutional-grade AI programming framework for automating scaffolding, architecture, and coding directly inside your software projects.
 
-## 📦 Quick Install
+## 📦 Quick Start
 
-The best way to initialize the AG-Kit in a new project is using `npx`:
+The best way to inject AG-Kit into any project is via `npx`:
 
 ```bash
-npx @mrtrinhvn/ag-kit init
-```
-
-> **Note**: This is the **recommended** method for remote machines as it avoids all `EACCES` permission issues.
+# 1. Khởi tạo bộ não (Inject .agent folder)
+npx @mrtrinhvn/ag-kit@latest init
 
-## 🛠 Global Usage & Commands
+# 2. Kiểm tra sức khỏe hệ thống (CDP, Ollama, Models)
+npx @mrtrinhvn/ag-kit@latest check
 
-You can also install it globally if you frequently create new projects:
-
-```bash
-npm install -g @mrtrinhvn/ag-kit
+# 3. Kiểm tra trạng thái và phiên bản
+npx @mrtrinhvn/ag-kit@latest status
 ```
 
-### 🛠 Local Development (Linking)
+---
 
-If you are developing Ag-Kit locally and want to use it globally without publishing to NPM:
+## 🛠 Lệnh CLI & Cách sử dụng
 
-1. Go to the Ag-Kit directory: `cd /home/tao/Projects/ag-kit`
-2. Run: `npm link` (This creates a global symlink)
-3. You can now use `ag-kit` anywhere!
+| Lệnh | Ý nghĩa | Chi tiết |
+|---|---|---|
+| `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. |
+| `ag-kit status` | **Trạng thái** | Hiển thị rõ: Phiên bản Tool (CLI) và Phiên bản Core (Brain) đang dùng. |
 
-### ❌ Troubleshooting: EACCES Permission Error
+### ⚙️ Cấu hình Cổng (Custom Port)
 
-If you see `npm error code EACCES` when installing globally via network (`npm install -g`), use one of these:
+Mặc định AG-Kit quét cổng **9555** và **9222**. Nếu bạn muốn dùng một cổng riêng cho từng dự án (để tránh xung đột khi mở nhiều IDE), hãy sửa file `.env`:
 
-**Solution 1: Use sudo (For quick global install)**
-```bash
-sudo npm install -g @mrtrinhvn/ag-kit
+```env
+CDP_PORT=12345
 ```
+Lệnh `ag-kit check` sẽ tự động ưu tiên cổng này để kết nối với IDE.
 
-**Solution 2: Use npx (Recommended - No sudo needed)**
-```bash
-npx @mrtrinhvn/ag-kit <command>
-```
-npx sẽ tự động tải và chạy mà không cần quyền ghi vào thư mục hệ thống.
+---
+
+## 🏗 Cấu trúc hệ thống (.agent)
 
-**Solution 3: Local Development (For this machine)**
-Follow [NPM's guide](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) to change the global directory to your home folder.
+Sau khi chạy `init`, dự án của bạn sẽ có bộ khung tiêu chuẩn:
+
+- **`GEMINI.md`**: "Hiến pháp" tối cao của Agent, đảm bảo tư duy hệ thống và an toàn.
+- **`agents/`**: Các đặc vụ chuyên trách (Orchestrator, Frontend, Backend, Debugger).
+- **`skills/`**: Các thuật toán tác chiến (Clean code, TDD, React Expert, Rust Pro...).
+- **`workflows/`**: Các lệnh gõ tắt (slash commands) như `/create`, `/plan`, `/debug`.
+- **`knowledge/`**: Nơi lưu giữ giao thức v3 và các kiến thức tự chữa lành (`self-healing`).
 
 ---
 
-Then use the provided CLI anywhere:
+## 🔄 Cập nhật & Bảo trì
 
-| Command | Description |
-|---|---|
-| `ag-kit init` | Scaffolds the `.agent` framework (Agents, Skills, Workflows) into your current directory. |
-| `ag-kit check` | Verifies environment health (CDP, Tokens, Ollama, Models). |
-| `ag-kit update` | Pulls the latest rules and templates and safely overwrites the core `.agent` folders without breaking your custom `knowledge/` base. |
-| `ag-kit status` | Checks exactly which version of the AG-Kit is active in your current working directory. |
+Chúng tôi liên tục cập nhật các kỹ năng mới từ dự án `ag-orchestrator`. Để đảm bảo "bộ não" của bạn luôn thông minh nhất:
 
-## 🧠 What's Inside the Brain?
+```bash
+# Luôn dùng @latest để lấy những tinh hoa mới nhất từ NPM
+npx @mrtrinhvn/ag-kit@latest update
+```
+
+---
 
-Running `ag-kit init` injects the following core architecture into your project:
+## ❌ Xử lý lỗi thường gặp (Troubleshooting)
 
-- **`GEMINI.md`**: The supreme constitution (Tier 0 Rules) ensuring the Agent always thinks systematically, acts safely, and never hallucinates code.
-- **`agents/`**: Core personas taking specialized roles (e.g., `orchestrator`, `frontend-specialist`, `backend-specialist`, `debugger`).
-- **`skills/`**: Tactical operational algorithms spanning from `clean-code` and `tdd-workflow` to `python-patterns` and `nextjs-react-expert`.
-- **`workflows/`**: Pre-defined step-by-step instructions (slash commands) like `/create`, `/plan`, `/brainstorm`, and `/debug`.
-- **`scripts/`**: CI/CD automation checkers like `lint_runner.py` and `security_scan.py`.
+**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`.
 
-## ⚙️ How It Works
-The AG-Kit is designed to be injected into an AI IDE or a custom Agent workspace.
-1. The AI reads `GEMINI.md` first.
-2. It assumes the persona of the relevant specialist in `agents/`.
-3. It selectively loads specific techniques from `skills/` based on context.
-4. It continuously documents important technical learnings in `knowledge/`.
+**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`.
 
 ---
 *Built with ❤️ to enforce Institutional-Grade Software Standards.*

package/bin/cli.js

@@ -73,7 +73,22 @@ program.command('init')
     const srcAgent = path.join(TEMPLATE_DIR, '.agent');
     if (!fs.existsSync(TARGET_AGENT_DIR)) {
       copyRecursiveSync(srcAgent, TARGET_AGENT_DIR);
+      // Ghi lại version vào .agent/.version
+      fs.writeFileSync(path.join(TARGET_AGENT_DIR, '.version'), pkg.version);
       console.log('\x1b[32m✅ Đã cài ráp thành công thư mục .agent vào Project!\x1b[0m');
+      
+      // Khởi tạo .env nếu chưa có
+      const envPath = path.join(process.cwd(), '.env');
+      if (!fs.existsSync(envPath)) {
+        fs.writeFileSync(envPath, 'CDP_PORT=9555\n');
+        console.log('\x1b[34mℹ️  Đã tạo file .env mẫu với CDP_PORT=9555\x1b[0m');
+      } else {
+        const envContent = fs.readFileSync(envPath, 'utf-8');
+        if (!envContent.includes('CDP_PORT=')) {
+          fs.appendFileSync(envPath, '\nCDP_PORT=9555\n');
+          console.log('\x1b[34mℹ️  Đã thêm cấu hình CDP_PORT=9555 vào file .env hiện tại\x1b[0m');
+        }
+      }
     } 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');
     }
@@ -102,6 +117,8 @@ program.command('update')
     });
 
     migrateLegacyMemories();
+    // Cập nhật version vào .agent/.version
+    fs.writeFileSync(path.join(TARGET_AGENT_DIR, '.version'), pkg.version);
     console.log('\x1b[32m✅ Cập nhật thành công 100% Cấu trúc kỹ năng siêu cấp!\x1b[0m');
   });
 
@@ -182,15 +199,22 @@ program.command('status')
   .action(() => {
     console.log('\x1b[36m📊 Trạng thái AG-Kit trong dự án hiện tại:\x1b[0m');
     if (fs.existsSync(TARGET_AGENT_DIR)) {
-      console.log('\x1b[32m✅ Trạng thái: Đã Cài Đặt (Active)\x1b[0m');
-      console.log(`📁 Đường dẫn : ${TARGET_AGENT_DIR}`);
+      console.log('\x1b[32m✅ Trạng thái  : Đã Cài Đặt (Active)\x1b[0m');
+      console.log(`📁 Đường dẫn    : ${TARGET_AGENT_DIR}`);
+      
+      const vPath = path.join(TARGET_AGENT_DIR, '.version');
+      if (fs.existsSync(vPath)) {
+        const 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)`);
+      }
+
+      console.log(`🏷  Bản Tool     : v${pkg.version}`);
       
-      try {
-          const pJson = require('../package.json');
-          console.log(`🏷  Phiên bản : v${pJson.version}`);
-      } catch (e) {}
     } 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ì. Gõ "ag-kit init" để Setup.\x1b[0m');
+      console.log(`🏷  Bản Tool     : v${pkg.version}`);
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
   "main": "index.js",
   "bin": {