lunar-skills 1.0.0

package/docs/architecture/feature-tree.md

@@ -0,0 +1,35 @@
+# 5. Feature Tree Documentation
+
+---
+
+## 🌲 5.1 System Feature Tree Diagram
+
+```mermaid
+graph TD
+    Root["PROACTIVE AI SKILL SYSTEM"] --> F1["Card & Prompt Management"]
+    Root --> F2["Scope Boundary Guard"]
+    Root --> F3["Hierarchical Card Compaction"]
+    Root --> F4["Visual System Diagrammer"]
+    Root --> F5["Multi-Category Tool Advisor"]
+
+    F1 --> F1_1["Auto-Create Card from Prompt"]
+    F1 --> F1_2["Auto-State Transition (Active -> DONE)"]
+    F1 --> F1_3["Proactive Idle Scope Trigger (Cạn Scope Notification)"]
+
+    F2 --> F2_1["Scope Rule Matrix (SCOPE_DIAGRAM, SCOPE_CORE_ENGINE...)"]
+    F2 --> F2_2["File Path Boundary Validation"]
+    F2 --> F2_3["Scope Violation Blocker"]
+
+    F3 --> F3_1["Level 0: Active Cards (< 10 Cards in cards.json)"]
+    F3 --> F3_2["Level 1: Milestone Compaction (10-in-1 JSON File)"]
+    F3 --> F3_3["Level 2: Executive Macro Report (100-in-1 Markdown Report)"]
+
+    F4 --> F4_1["C4 Architecture Mermaid Graph"]
+    F4 --> F4_2["Compaction Flowchart Visualizer"]
+    F4 --> F4_3["Live Card Status Tracker Table"]
+
+    F5 --> F5_1["Static Web Advice (HTML5 + Cloudflare/Vercel)"]
+    F5 --> F5_2["Cloud Backend Advice (Supabase / Firebase)"]
+    F5 --> F5_3["Payment Advice (VietQR / PayOS / Stripe)"]
+    F5 --> F5_4["Notification Advice (Telegram / Zalo ZNS / Resend)"]
+```

package/docs/architecture/folder-structure.md

@@ -0,0 +1,81 @@
+# 1. Folder Structure Documentation
+
+**Project Name:** Universal Proactive AI Skill System & Card Compaction Architecture  
+**Generated At:** 2026-07-27  
+
+---
+
+## 🌳 1.1 Tree Structure (Source Code Fact)
+
+```text
+/Volumes/sdd anh/skill/
+├── README.md                            # Open-source community installation & usage guide
+├── package.json                         # Node.js manifest & npm scripts
+├── index.html                           # Live Mermaid.js visual architecture dashboard
+│
+├── .gemini/
+│   └── skills/                          # Custom AI Skill Definitions
+│       ├── auto-idea-to-product/
+│       │   └── SKILL.md                 # Proactive Card Engine & Compaction Skill
+│       └── system-architecture-diagrammer/
+│           └── SKILL.md                 # Visual System Diagrammer Skill
+│
+├── data/                                # Persistent Data Storage Layer
+│   ├── cards.json                       # Level 0: Active task cards array (Max < 10)
+│   ├── milestones/                      # Level 1: Compacted 10-in-1 milestone JSON files
+│   └── reports/                         # Level 2: Compacted 100-in-1 executive markdown reports
+│
+├── scripts/                             # Core Business Engine Scripts
+│   ├── card-manager.js                  # Proactive Card Engine & 10-to-1 Compaction logic
+│   └── scope-enforcer.js                # Strict Scope Boundary Enforcer Guard
+│
+├── src/                                 # Runtime HTTP API Server
+│   └── index.js                         # Native HTTP server serving /api/cards & static files
+│
+└── docs/                                # Enterprise Architectural Documentation
+```
+
+---
+
+## 📁 1.2 Thư mục & Vai trò Kỹ thuật
+
+```mermaid
+graph TD
+    Root["/ (Root Project)"] --> Gemini[".gemini/skills (AI Skills)"]
+    Root --> Data["data/ (JSON & Markdown Storage)"]
+    Root --> Scripts["scripts/ (Engine & Scope Guard)"]
+    Root --> Src["src/ (Native HTTP Server)"]
+    Root --> Docs["docs/ (Architectural Specs)"]
+
+    Data --> Cards["cards.json (Level 0 Active)"]
+    Data --> Milestones["milestones/ (Level 1 Milestone Files)"]
+    Data --> Reports["reports/ (Level 2 Macro Reports)"]
+
+    Scripts --> CardMgr["card-manager.js (Proactive Engine)"]
+    Scripts --> ScopeEnf["scope-enforcer.js (Boundary Guard)"]
+
+    Src --> IndexJS["index.js (HTTP Server Port 3000)"]
+```
+
+---
+
+## 🔗 1.3 Dependency giữa các Package / Modules
+
+```mermaid
+graph LR
+    SrcIndex["src/index.js"] -->|require| CardMgr["scripts/card-manager.js"]
+    CardMgr -->|require| ScopeEnf["scripts/scope-enforcer.js"]
+    CardMgr -->|read/write| DataCards["data/cards.json"]
+    CardMgr -->|write| DataMilestones["data/milestones/"]
+    CardMgr -->|write| DataReports["data/reports/"]
+    SrcIndex -->|serves static| IndexHTML["index.html"]
+```
+
+---
+
+## 🏷 1.4 Quy Tắc Đặt Tên (Naming Conventions)
+
+- **File JavaScript**: `kebab-case.js` (Ví dụ: `card-manager.js`, `scope-enforcer.js`).
+- **File JSON Data**: `kebab-case.json` / `UPPERCASE.json` (Ví dụ: `cards.json`, `MILESTONE-001.json`).
+- **File Skill**: `SKILL.md` đặt trong thư mục tên skill dạng `kebab-case` (Ví dụ: `.gemini/skills/auto-idea-to-product/SKILL.md`).
+- **Scopes**: `UPPERCASE_SNAKE_CASE` (Ví dụ: `SCOPE_DIAGRAM`, `SCOPE_CORE_ENGINE`, `SCOPE_SECURITY`, `SCOPE_PAYMENT`).

package/docs/architecture/module-diagram.md

@@ -0,0 +1,43 @@
+# 4. Module Diagram Documentation
+
+---
+
+## 🧩 4.1 Module Relationship Diagram
+
+```mermaid
+graph TD
+    M1["Card Manager Module (scripts/card-manager.js)"]
+    M2["Scope Guard Module (scripts/scope-enforcer.js)"]
+    M3["API Server Module (src/index.js)"]
+    M4["Diagram Visualizer Module (index.html)"]
+    M5["Compaction Engine Module (scripts/card-manager.js)"]
+
+    M3 -->|Imports| M1
+    M1 -->|Imports| M2
+    M1 -->|Invokes| M5
+    M4 -->|Fetches Data / Embeds| M3
+```
+
+---
+
+## 📋 4.2 Module Specification Table
+
+### 1. Card Manager Module
+- **Responsibility**: Khởi tạo thẻ mới từ prompt, chuyển thẻ cũ sang DONE, tư vấn bộ công cụ đa dạng và kiểm tra trạng thái Cạn Scope.
+- **Dependency**: `scripts/scope-enforcer.js`, `data/cards.json`.
+- **Public API**: `processUserPrompt()`, `checkIdleScopeState()`, `adviseToolsFromPrompt()`.
+
+### 2. Scope Guard Module
+- **Responsibility**: Định nghĩa bảng quy tắc ranh giới Scope (`SCOPE_DIAGRAM`, `SCOPE_CORE_ENGINE`, `SCOPE_SECURITY`, `SCOPE_PAYMENT`, `GLOBAL_SCOPE`) và kiểm tra tính hợp lệ khi sửa file.
+- **Dependency**: Native Node.js `path` module.
+- **Public API**: `ScopeEnforcer.validateAction(scopeName, targetFilePath)`.
+
+### 3. Compaction Engine Module
+- **Responsibility**: Tự động gom nén 10 Thẻ Lẻ hoàn thành thành 1 File Milestone (`MILESTONE-xxx.json`) và nén 10 Milestones thành 1 Báo cáo Macro (`MASTER_REPORT-xxx.md`).
+- **Dependency**: Native Node.js `fs` & `path` modules.
+- **Public API**: `compactCardsIfNeeded()`, `compactMilestonesIfNeeded()`.
+
+### 4. API Server Module
+- **Responsibility**: Phục vụ static file `index.html` và cung cấp các REST API Endpoints `/api/health`, `/api/skills`, `/api/cards`.
+- **Dependency**: `http`, `fs`, `path`, `url`, `scripts/card-manager.js`.
+- **Public API**: HTTP Server Port 3000.

package/docs/architecture/package-diagram.md

@@ -0,0 +1,26 @@
+# 2. Package Diagram Documentation
+
+Dựa trên phân tích codebase hiện tại, hệ thống sử dụng cấu trúc **Native Lightweight Controller-Service-Storage Architecture** không dùng framework nặng.
+
+---
+
+## 📦 2.1 Package Architecture Flow
+
+```mermaid
+graph TD
+    Client["Client / User / Terminal"] -->|HTTP REST / CLI| Controller["Controller (src/index.js)"]
+    Controller -->|Delegates Logic| Service["Service / Engine (scripts/card-manager.js)"]
+    Service -->|Validates Action| Guard["Guard / Enforcer (scripts/scope-enforcer.js)"]
+    Service -->|Persists Data| Storage["Storage Layer (data/cards.json & milestones/)"]
+```
+
+---
+
+## 🔍 2.2 Chi Tiết Các Tầng (Layers)
+
+| Tầng (Layer) | File đại diện | Vai trò kỹ thuật |
+| :--- | :--- | :--- |
+| **Controller Layer** | `src/index.js` | Tiếp nhận HTTP Request (`GET /api/cards`, `POST /api/cards`, `GET /api/health`), định tuyến MIME types và phản hồi JSON. |
+| **Service Layer** | `scripts/card-manager.js` | Xử lý logic tạo thẻ từ prompt, nén thẻ phân cấp 10-in-1, tự động phát hiện Cạn Scope (IDLE) và tư vấn bộ công cụ đa dạng. |
+| **Guard / Boundary Layer** | `scripts/scope-enforcer.js` | Kiểm tra ranh giới file path tương ứng với Scope được giao (`SCOPE_DIAGRAM`, `SCOPE_CORE_ENGINE`, etc.). |
+| **Storage Layer** | `data/cards.json`<br>`data/milestones/`<br>`data/reports/` | Nơi lưu trữ bền vững phẳng dạng JSON & Markdown. |

package/docs/architecture/system-architecture.md

@@ -0,0 +1,42 @@
+# 3. System Architecture Documentation
+
+**Architecture Pattern:** Event-Driven Proactive Skill Engine with Hierarchical File Compaction.
+
+---
+
+## 🏗 3.1 Overall System Architecture Diagram
+
+```mermaid
+graph TD
+    User["👤 User / Terminal / Gemini Prompt"] -->|CLI Prompt / HTTP| Frontend["Frontend / Dashboard (index.html)"]
+    Frontend -->|HTTP API / REST| APIServer["API Server (src/index.js)"]
+    
+    subgraph Core_Skill_System ["Core Skill System"]
+        APIServer --> CardManager["Card Manager Engine (scripts/card-manager.js)"]
+        CardManager --> ScopeGuard["Scope Enforcer Guard (scripts/scope-enforcer.js)"]
+        
+        subgraph Storage_Tier ["Storage Tier (File Persistence)"]
+            CardManager --> CardsJSON["Level 0: data/cards.json (< 10 Active Cards)"]
+            CardsJSON -->|Compaction Engine (10-in-1)| Milestones["Level 1: data/milestones/MILESTONE-001.json"]
+            Milestones -->|Macro Summarizer (100-in-1)| MasterReport["Level 2: data/reports/MASTER_REPORT_001.md"]
+        end
+
+        subgraph Proactive_System ["Proactive AI Engine"]
+            CardManager --> IdleDetector["Idle Scope Trigger (checkIdleScopeState)"]
+            CardManager --> ToolAdvisor["Multi-Category Tool Advisor"]
+        end
+    end
+
+    ExternalServices["External 3rd-Party Services (Not Implemented / Proposed)"]
+    Proactive_System -->|Proposed Integration| ExternalServices
+```
+
+---
+
+## 📊 3.2 System Component Status
+
+- **Frontend / Dashboard**: Implemented (`index.html` with Mermaid.js visual rendering).
+- **API Server**: Implemented (`src/index.js` port 3000 native HTTP server).
+- **Core Engine & Scope Guard**: Implemented (`scripts/card-manager.js`, `scripts/scope-enforcer.js`).
+- **File Persistence Storage**: Implemented (`data/cards.json`, `data/milestones/`, `data/reports/`).
+- **Redis / Distributed Queue / DB Cluster**: *Not Implemented* (Dự án sử dụng File-based Persistence phẳng cực nhẹ).

package/docs/architecture.html

@@ -0,0 +1,193 @@
+<!DOCTYPE html>
+<html lang="vi">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>DOCS SYSTEM ARCHITECTURE & VISUAL DIAGRAMS</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Outfit:wght@700;900&family=Plus+Jakarta+Sans:wght@400;600;700&family=Space+Grotesk:wght@500;700&display=swap" rel="stylesheet">
+  
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+  <script>
+    mermaid.initialize({
+      startOnLoad: true,
+      theme: 'dark',
+      themeVariables: {
+        darkMode: true,
+        background: '#080c18',
+        primaryColor: '#00ff66',
+        primaryTextColor: '#ffffff',
+        primaryBorderColor: '#00ff66',
+        lineColor: '#00f0ff',
+        secondaryColor: '#162036',
+        tertiaryColor: '#0e1424'
+      }
+    });
+  </script>
+
+  <style>
+    :root {
+      --bg-dark: #050811;
+      --bg-card: #0e1424;
+      --accent-neon: #00ff66;
+      --accent-cyan: #00f0ff;
+      --accent-magenta: #ff0055;
+      --text-main: #ffffff;
+      --text-muted: #94a3b8;
+      --border-sharp: 1px solid rgba(0, 255, 102, 0.25);
+      --font-mono: 'Space Grotesk', monospace;
+      --font-title: 'Outfit', sans-serif;
+    }
+
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      background-color: var(--bg-dark);
+      color: var(--text-main);
+      font-family: 'Plus Jakarta Sans', sans-serif;
+      padding: 2rem;
+      line-height: 1.6;
+    }
+
+    .header-dashboard {
+      max-width: 1440px;
+      margin: 0 auto 2rem auto;
+      border-bottom: var(--border-sharp);
+      padding-bottom: 1.5rem;
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-end;
+      flex-wrap: wrap;
+      gap: 1rem;
+    }
+
+    .header-dashboard h1 {
+      font-family: var(--font-title);
+      font-size: 2.2rem;
+      letter-spacing: 2px;
+      text-transform: uppercase;
+    }
+
+    .header-dashboard h1 span { color: var(--accent-neon); }
+
+    .tag-badge {
+      font-family: var(--font-mono);
+      background: rgba(0, 255, 102, 0.15);
+      color: var(--accent-neon);
+      border: 1px solid var(--accent-neon);
+      padding: 4px 12px;
+      font-size: 0.8rem;
+      letter-spacing: 1px;
+    }
+
+    .grid-container {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(680px, 1fr));
+      gap: 2rem;
+      max-width: 1440px;
+      margin: 0 auto;
+    }
+
+    .doc-card {
+      background: var(--bg-card);
+      border: var(--border-sharp);
+      padding: 1.8rem;
+      clip-path: polygon(0 0, 100% 0, 100% calc(100% - 20px), calc(100% - 20px) 100%, 0 100%);
+      display: flex;
+      flex-direction: column;
+    }
+
+    .doc-title {
+      font-family: var(--font-mono);
+      font-size: 1.05rem;
+      color: var(--accent-cyan);
+      letter-spacing: 1px;
+      margin-bottom: 1.2rem;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      border-bottom: 1px solid rgba(255,255,255,0.08);
+      padding-bottom: 0.6rem;
+    }
+
+    .mermaid-box {
+      flex: 1;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: #080c18;
+      border: 1px dashed rgba(0, 255, 102, 0.2);
+      padding: 1.5rem;
+      overflow: auto;
+      min-height: 280px;
+    }
+
+    footer {
+      max-width: 1440px;
+      margin: 3rem auto 0 auto;
+      text-align: center;
+      font-family: var(--font-mono);
+      font-size: 0.8rem;
+      color: var(--text-muted);
+      border-top: 1px solid rgba(255,255,255,0.05);
+      padding-top: 1.5rem;
+    }
+  </style>
+</head>
+<body>
+
+  <header class="header-dashboard">
+    <div>
+      <span class="tag-badge">DOCS ISOLATED SYSTEM ARCHITECTURE</span>
+      <h1>SYSTEM ARCHITECTURE <span>VISUAL DIAGRAMS</span></h1>
+    </div>
+    <div style="font-family: var(--font-mono); color: var(--text-muted); font-size: 0.85rem;">
+      OUTPUT LOCATION: <span style="color: var(--accent-neon);">DOCS/ARCHITECTURE.HTML</span>
+    </div>
+  </header>
+
+  <div class="grid-container">
+    
+    <!-- System Architecture Graph -->
+    <div class="doc-card">
+      <div class="doc-title">
+        <span>🏗 SYSTEM ARCHITECTURE (docs/architecture.html)</span>
+      </div>
+      <div class="mermaid-box">
+        <pre class="mermaid">
+graph TD
+    User["👤 User / Terminal Prompt"] --> APIServer["Native HTTP Server (src/index.js:3000)"]
+    APIServer --> CardManager["Card Manager Engine (scripts/card-manager.js)"]
+    CardManager --> ScopeGuard["Scope Enforcer Guard (scripts/scope-enforcer.js)"]
+    
+    subgraph Storage_Tier ["3-Tier File Persistence"]
+        CardManager --> Level0["Level 0: cards.json (< 10 Active)"]
+        Level0 -->|10-in-1 Compaction| Level1["Level 1: data/milestones/MILESTONE-001.json"]
+        Level1 -->|100-in-1 Compaction| Level2["Level 2: data/reports/MASTER_REPORT_001.md"]
+    end
+        </pre>
+      </div>
+    </div>
+
+    <!-- Hierarchical Compaction Flowchart -->
+    <div class="doc-card">
+      <div class="doc-title">
+        <span>🗂 HIERARCHICAL COMPACTION FLOWCHART</span>
+      </div>
+      <div class="mermaid-box">
+        <pre class="mermaid">
+flowchart LR
+    RawCards["Tầng 0: 10 Thẻ Lẻ (cards.json)"] -->|Compaction Engine| Milestones["Tầng 1: MILESTONE-001.json"]
+    Milestones -->|Executive Summarizer| MasterReports["Tầng 2: MASTER_REPORT_001.md"]
+        </pre>
+      </div>
+    </div>
+
+  </div>
+
+  <footer>
+    DOCS ISOLATED ARCHITECTURE VISUALIZER // SAVED IN DOCS/ARCHITECTURE.HTML
+  </footer>
+</body>
+</html>

package/docs/database/database.md

@@ -0,0 +1,67 @@
+# 7. Database Documentation
+
+**Database Status:** File-Based JSON & Markdown Multi-Tier Persistence Storage (PostgreSQL/SQL Database was explicitly removed per user decision to keep the skill 100% lightweight).
+
+---
+
+## 🗄 7.1 Data Storage ERD Diagram (JSON Schema Entities)
+
+```mermaid
+erDiagram
+    CARD {
+        string id PK
+        string prompt
+        string title
+        string scope FK
+        string category
+        string status
+        string createdAt
+        string completedAt
+    }
+
+    MILESTONE {
+        string milestoneId PK
+        string compactedAt
+        int totalCardsCompacted
+        string_array scopesIncluded
+        string summary
+    }
+
+    MASTER_REPORT {
+        string reportId PK
+        string generatedAt
+        int totalMilestonesCompacted
+    }
+
+    CARD ||--o{ MILESTONE : "compacted into (10 cards -> 1 milestone)"
+    MILESTONE ||--o{ MASTER_REPORT : "compacted into (10 milestones -> 1 report)"
+```
+
+---
+
+## 📋 7.2 Storage File Schemas
+
+### 1. Active Cards File (`data/cards.json`)
+- **Type**: Array of Card Objects (Level 0 Persistence).
+- **Max Capacity**: 10 Active Cards (Compaction Engine automatically purges completed cards when count >= 10).
+- **Field Definitions**:
+  - `id` (String, Unique PK): E.g., `"CARD-001"`.
+  - `prompt` (String): Raw user input from Gemini/Terminal.
+  - `title` (String): Generated task summary title.
+  - `scope` (String): Assigned Scope Boundary (`SCOPE_DIAGRAM`, `SCOPE_CORE_ENGINE`, etc.).
+  - `category` (String): Task category.
+  - `status` (String): Status Enum (`"IN_PROGRESS"`, `"DONE"`, `"WAITING_USER_APPROVAL"`, `"PROPOSED_BY_AI"`).
+  - `createdAt` (String): ISO 8601 Timestamp.
+  - `completedAt` (String, Optional): ISO 8601 Timestamp when finished.
+
+### 2. Milestone Files (`data/milestones/MILESTONE-xxx.json`)
+- **Type**: Single JSON Document per 10 Completed Cards (Level 1 Persistence).
+- **Fields**:
+  - `milestoneId`: E.g., `"MILESTONE-001"`.
+  - `compactedAt`: ISO 8601 Timestamp.
+  - `totalCardsCompacted`: Integer (10).
+  - `scopesIncluded`: Array of Strings (Unique scopes in this batch).
+  - `cards`: Array of 10 complete Card objects.
+
+### 3. Executive Macro Reports (`data/reports/MASTER_EXECUTIVE_REPORT_xxx.md`)
+- **Type**: Markdown Document per 10 Milestones / 100 Cards (Level 2 Persistence).

package/docs/deployment/deployment.md

@@ -0,0 +1,26 @@
+# 12. Deployment Documentation
+
+**Deployment Status:** Native Node.js Zero-Dependency Deployment (Docker & SQL were explicitly removed per user decision to ensure 100% lightweight skill execution).
+
+---
+
+## 🚀 12.1 Native Node.js Deployment Flow
+
+```mermaid
+graph TD
+    Developer["Developer / Agent Environment"] -->|1. Push to Repository| GitRepo["Git Repository"]
+    GitRepo -->|2. Pull Latest Code| Server["Target Host / Local Server"]
+    Server -->|3. Run Startup Script| StartCmd["npm start (node src/index.js)"]
+    StartCmd -->|4. Port 3000 Listening| LiveServer["HTTP API Server Live (http://localhost:3000)"]
+    LiveServer -->|5. Serves Static UI| Dashboard["Visual Dashboard (http://localhost:3000/index.html)"]
+```
+
+---
+
+## 📦 12.2 Deployment Checklist
+
+- [x] Node.js >= v18 installed on host.
+- [x] Dependencies installed (`npm install`).
+- [x] Data directories exist (`data/`, `data/milestones/`, `data/reports/`).
+- [x] HTTP Server port 3000 open.
+- [ ] *Docker Containerization*: **Not Implemented** (Removed per user decision).

package/docs/infrastructure/cicd.md

@@ -0,0 +1,26 @@
+# 14. CI/CD Pipeline Documentation
+
+**CI/CD Status:** Local Direct Execution & Verification Mode (Automated CI/CD Actions Pipeline is *Not Implemented*, proposed blueprint below).
+
+---
+
+## 🔄 14.1 Proposed CI/CD Pipeline Diagram
+
+```mermaid
+graph TD
+    Dev["Developer"] -->|Git Commit & Push| GitHub["GitHub Repository"]
+    GitHub -->|Trigger Workflow| Actions["GitHub Actions CI/CD"]
+    
+    subgraph CI_Pipeline ["CI Pipeline"]
+        Actions --> Step1["1. Checkout Code"]
+        Step1 --> Step2["2. Setup Node.js v20"]
+        Step2 --> Step3["3. Install Dependencies (npm ci)"]
+        Step3 --> Step4["4. Run Scope Enforcer Tests (node scripts/scope-enforcer.js)"]
+        Step4 --> Step5["5. Run Card Engine Verification (node scripts/card-manager.js)"]
+    end
+
+    subgraph CD_Pipeline ["CD Pipeline"]
+        Step5 -->|Tests Passed| Step6["6. Deploy to Production Host / Vercel"]
+        Step6 --> Step7["7. Health Check Verification (GET /api/health)"]
+    end
+```

package/docs/infrastructure/infrastructure.md

@@ -0,0 +1,21 @@
+# 13. Infrastructure Documentation
+
+---
+
+## 🌐 13.1 Infrastructure Topology Diagram
+
+```mermaid
+graph TD
+    Client["Client Browser / Terminal CLI"] -->|HTTP / Localhost| NodeServer["Node.js HTTP Server (src/index.js:3000)"]
+    
+    subgraph Host_Environment ["Local Host Environment"]
+        NodeServer --> Engine["Scripts Layer (card-manager.js & scope-enforcer.js)"]
+        Engine --> LocalStorage["File System Storage (data/cards.json)"]
+    end
+
+    subgraph Proposed_Cloud_Infrastructure ["Proposed Cloud Infrastructure (Not Implemented)"]
+        Cloudflare["Cloudflare Edge CDN"] --> LoadBalancer["Nginx Load Balancer"]
+        LoadBalancer --> AppCluster["Node.js Application Cluster"]
+        AppCluster --> CloudStorage["Supabase / Cloud Object Storage"]
+    end
+```

package/docs/infrastructure/logging.md

@@ -0,0 +1,24 @@
+# 15. Logging Architecture Documentation
+
+---
+
+## 🪵 15.1 Logging Architecture Diagram
+
+```mermaid
+graph TD
+    Engine["card-manager.js / scope-enforcer.js"] -->|Console Log / Error| Console["Standard Console Output (stdout/stderr)"]
+    Console -->|Audit Log Entries| AuditJSON["data/milestones/ & cards.json Log Entries"]
+    
+    subgraph Proposed_Enterprise_Logging ["Proposed Enterprise Logging Stack (Not Implemented)"]
+        Console -->|Winston / Pino Logger| LogShipper["FluentBit Log Shipper"]
+        LogShipper --> ELK["Elasticsearch / Kibana Dashboard"]
+    end
+```
+
+---
+
+## 📋 15.2 Current Log Event Types
+
+1. `[COMPACTION ENGINE] ⚡ Đã nén 10 Thẻ Lẻ thành Milestone File: MILESTONE-xxx.json`
+2. `[BẢO VỆ SCOPE] Hành động bị CHẶN! Thẻ hiện tại có scope là [SCOPE_X], không được phép sửa file [FILE_Y].`
+3. `[AGY Server] Listening on http://localhost:3000`

package/docs/infrastructure/monitoring.md

@@ -0,0 +1,18 @@
+# 16. Monitoring & Health Architecture Documentation
+
+---
+
+## 📈 16.1 Health & Monitoring Flow
+
+```mermaid
+graph TD
+    Monitor["Monitoring Probe / UptimeRobot"] -->|HTTP GET /api/health| Server["src/index.js"]
+    Server -->>Monitor: 200 OK { status: "UP", timestamp: "..." }
+
+    subgraph Proposed_Prometheus_Grafana ["Proposed Production Monitoring (Not Implemented)"]
+        Server -->|Prometheus Metrics Middleware| PromExporter["/metrics Endpoint"]
+        PromExporter --> Prometheus["Prometheus Server"]
+        Prometheus --> Grafana["Grafana Visual Dashboard"]
+        Prometheus --> AlertManager["AlertManager (Telegram / Email Alerts)"]
+    end
+```

package/docs/security/security.md

@@ -0,0 +1,35 @@
+# 17. Security Architecture Documentation
+
+---
+
+## 🛡 17.1 Security Enforcement Architecture Diagram
+
+```mermaid
+graph TD
+    UserAction["User / AI Agent Action"] --> ScopeGuard["scripts/scope-enforcer.js (Scope Guard)"]
+    
+    ScopeGuard -->|Check 1| ScopeCheck{"Target File in Allowed Scope Paths?"}
+    ScopeCheck -->|No| Block1["SCOPE_VIOLATION_BLOCKED (Action Prevented ⛔)"]
+    
+    ScopeCheck -->|Yes| SanitizationCheck{"Input Sanitized?"}
+    SanitizationCheck -->|Yes| PassAction["Action Allowed (SCOPE_PASSED ✅)"]
+
+    subgraph Defense_in_Depth ["Defense-In-Depth Security Layer"]
+        DirectoryTraversalGuard["Path Traversal Prevention (src/index.js)"]
+        TokenBudgetGuard["Token Budget Guard (Max 2 Retries Limit)"]
+    end
+
+    PassAction --> Defense_in_Depth
+```
+
+---
+
+## 📋 17.2 Security Implementation Checklist
+
+| Category | Status in Codebase | Implementation Details |
+| :--- | :--- | :--- |
+| **Scope Boundary Guard** | **IMPLEMENTED** | `scripts/scope-enforcer.js` blocks unauthorized file edits outside active card scope (`SCOPE_DIAGRAM`, `SCOPE_CORE_ENGINE`, etc.). |
+| **Directory Traversal Defense** | **IMPLEMENTED** | `src/index.js` verifies `filePath.startsWith(PUBLIC_DIR)` before serving static files. |
+| **Token Budget Protection** | **IMPLEMENTED** | `scripts/card-manager.js` limits max 2 retries per bug to prevent token exhaustion loops. |
+| **CORS Restriction** | **IMPLEMENTED** | Headers set in `src/index.js`. |
+| **OAuth / JWT / Password Hashing** | *Not Implemented* | Proposed in `docs/api/authentication-flow.md` for production deployment. |

package/docs/workflow/sequence-card-creation.md

@@ -0,0 +1,26 @@
+# 9. Sequence Diagram - Card Creation Workflow
+
+---
+
+## 🔄 9.1 Sequence Diagram: Create Task Card from User Prompt
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as User / Terminal
+    participant Server as src/index.js (HTTP API)
+    participant Engine as card-manager.js (Card Engine)
+    participant Guard as scope-enforcer.js (Scope Guard)
+    participant Storage as data/cards.json
+
+    User->>Server: POST /api/cards { prompt: "Tích hợp mã ngân hàng" }
+    Server->>Engine: processUserPrompt("Tích hợp mã ngân hàng")
+    Engine->>Engine: detectScopeFromPrompt() => "SCOPE_PAYMENT"
+    Engine->>Guard: validateAction("SCOPE_PAYMENT", "scripts/card-manager.js")
+    Guard-->>Engine: { allowed: true, status: "SCOPE_PASSED" }
+    Engine->>Engine: Set previous active cards to DONE
+    Engine->>Storage: Save new CARD-xxx with IN_PROGRESS
+    Engine->>Engine: compactCardsIfNeeded()
+    Engine-->>Server: Return New Card Object
+    Server-->>User: 201 Created { status: "SUCCESS", card: CARD-xxx }
+```